Larian Studios

Osiris API Documentation Wishlist

Posted By: Windemere

Osiris API Documentation Wishlist - 27/11/17 05:55 PM

Sorry about the length, but here are some of my most wanted documentation items. Other folks can feel free to jump in on this thread with wiki API documentation requests of their own.

1. Users, Players, and Parties, Oh My!

In general, it would be helpful to have more information on how the categories of Users, Players, and Parties are organized and handled in Osiris. From what I have gathered, this is roughly how it plays out:

User: A human with a unique profile currently playing the game

Player: Any character that somehow belongs to a human controlled party, including summons. Basically, anything that is not actively controlled by AI.

Party: A grouping of all players assigned to a particular user. If there are two users playing a game together, are there two parties or one? Do summons show up in a party iteration?

Specific related APIs needing documentation:
CharacterAddToParty()
CharacterAddToPlayerCharacter()
MakePlayerActive()
IterateParty
IterateParties
IterateUsers
CharacterIsControlled():
Does this mean actively selected and controlled or simply that it is a player? Could it be a player that is taunted or charmed?

Specific question related to best practices:
What does CharacterAddToParty() do that isn't impicitly handled by CharacterAssignToUser()? Why is it in the Origins campaign that CharacterAddToParty() is not called in the same frame as CharacterMakePlayer() and CharacterAssignToUser() during the PROC_EndLohseSaheilaMoment()? What's the significance of knowing Lohse's original faction in a DB variable before deciding to add her to the party?

The use of "AVATAR" tag:
This appears to be a way of designating characters made or selected via character creation? The tag makes its way into the shared library via SelectAndStartDialog(), presumably for sorting out issues related to dialogs with Origin recruited characters. This tag also appears to be responsible for adding the little crown in the UI portrait for the character. Is this hard-coded? Could we change the tag to something else and still get the crown in the UI?

Player Control:
Is there any way to detect that a player has switched to a new active player via double clicking their portrait in the UI?


Camera Issues

It would be nice to get official documentation on CameraActivate() and Spectator Camera Triggers in general. I've already found that setting _Time to -1.0 makes it last indefinitely and 0.0 deactivates the camera view. There are, however, some tricky issues I have noticed with respect to camera timing and any developer notes would be great. For instance:

+ Changing an atmosphere while a spectactor camera is actived and inside the atmosphere does not exhibit the atmosphere change. It seems like the game requires some kind of camera event to take place (either camera moving or a new camera getting (re-)activated) for the atmosphere change to show.

+ The call seems to fail, get lost, or overriden in certain situations. For instance, if a user connects in a multi-player game and you try to use CameraActivate() right away, it doesn't work. There seems to be a delay between when a user is "in game" and their camera is functional, and if you try to activate a camera too early it won't work. Are there other situations like this that are known?


Game Start Events

The following events aren't documented yet and it would be helpful to understand more precisely when they are fired:

GameModeStarted
CharacterCreationStarted



Thank you for your time smile
Posted By: LarIlya

Re: Osiris API Documentation Wishlist - 28/11/17 08:24 AM

Hi Windemere.
Most of your questions will require some looking into, but I can offer this much right now:
You're right on what the terms Player and User usually denote.

However, a "party" is a group of users (as you correctly said, humans with a unique profile currently playing the game) and their associated character.
It's the same entity player can leave or join by using the "leave party" or "kick from party" options when right-clicking on another user's character, and the same entity they implicitly leave when using the Make War option.

The AVATAR tag is indeed used in order to track which character went through character creation, as opposed to the companions, who are recruited later. They're considered the player's "main" character. Code checks that tag explicitly, though, so replacing it isn't really possible. Why do you want to?

As for Lohse's faction, it seems to me that the only reason to know that is so it can be reinstated when she is added to party again.
Posted By: Windemere

Re: Osiris API Documentation Wishlist - 28/11/17 01:11 PM

Originally Posted by LarIlya
The AVATAR tag is indeed used in order to track which character went through character creation, as opposed to the companions, who are recruited later. They're considered the player's "main" character. Code checks that tag explicitly, though, so replacing it isn't really possible. Why do you want to?


Thanks for the reply. It's mostly a matter of wanting to understand whether we need it or not in standalone campaigns. It just so happens to be an unfortunate term for me since I'm making an Ultima themed campaign where you are NOT the Avatar so it could be confusing to the player when they hover their mouse over their portrait and see AVATAR. laugh Do you know if the engine looks for this tag in any other places than the UI? If not, we can probably leave the tag out in a standalone campaign and add our own SelectAndStartDialog() story frames to handle a differently named tag if we ever needed that functionality.

Thanks again!
Posted By: Windemere

Re: Osiris API Documentation Wishlist - 28/11/17 01:15 PM

Another character creation related call I should have added to my initial list is CharacterSelectedInCharCreation(). It's probably pretty straightforward but always nice to know whether there are any important notes to go along with it.
Posted By: Windemere

Re: Osiris API Documentation Wishlist - 28/11/17 02:57 PM

And one more please:

event CharacterCharacterEvent((CHARACTERGUID)_Character1, (CHARACTERGUID)_Character2, (STRING)_Event)



... and thanks for the quick response on this, I see wiki updates already today with some useful notes in there!

thankyou
Posted By: Larian_Koala

Re: Osiris API Documentation Wishlist - 28/11/17 08:08 PM

Hi Windemere,

Originally Posted by Windemere

The following events aren't documented yet and it would be helpful to understand more precisely when they are fired:

GameModeStarted
CharacterCreationStarted



Unfortunately the event CharacterCreationStarted is a pretty complex event that gets thrown around. Something I can say about it is basically any time a character is changed/created, this event will be thrown (this includes switching between races).

GameModeStarted happens pretty much exactly as you would expect it to, when you switch from one game mode to another this will trigger. It should happen towards the end of the loading screen (e.g. Arena -> Create -> "Trigger on entering lobby").
An exception here is this isn't called when switching back to the main menu and it isn't called on loading a level.

Hope this helps you somewhat.

Regards,
Koala

Posted By: Larian_Koala

Re: Osiris API Documentation Wishlist - 28/11/17 08:13 PM

Originally Posted by Windemere
The use of "AVATAR" tag:
This appears to be a way of designating characters made or selected via character creation? The tag makes its way into the shared library via SelectAndStartDialog(), presumably for sorting out issues related to dialogs with Origin recruited characters. This tag also appears to be responsible for adding the little crown in the UI portrait for the character. Is this hard-coded? Could we change the tag to something else and still get the crown in the UI?


Unfortunately this is hardcoded and you'll need to use a different Tag. However remember that tags that appear in the character sheet are translated, so you can have a tag "MOD_AVATAR" and the translation for it is "Avatar". We never expose the tag "AVATAR" in game, so you shouldn't have to worry about visual duplication.

Regards,
Koala
Posted By: Tinkerer

Re: Osiris API Documentation Wishlist - 29/11/17 05:08 PM

Originally Posted by Windemere

Specific question related to best practices:
What does CharacterAddToParty() do that isn't impicitly handled by CharacterAssignToUser()?

I have extended the documentation of CharacterAssignToUser and added documentation for CharacterAddToParty. The answer to your question is: nothing, CharacterAddToParty won't do anything extra. I know the Lohse/Saheila moment has been plagued by a lot of issues over time, so that was probably just added at some point trying to solve things, and never removed.
Posted By: Windemere

Re: Osiris API Documentation Wishlist - 29/11/17 05:17 PM

Yes, I've been watching, great job with the latest additions! They're very helpful, and I appreciate the follow-up on this particular question as well. Sounds reasonable. smile
© 2020 Larian Studios forums