Difference between revisions of "Osiris API Tips Events"
(Created page with "test") |
|||
| (3 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | + | = Events = | |
| + | |||
| + | <p>Events are a way for Osiris to inform script that something happened. All event parameters have [in] semantics.</p> | ||
| + | |||
| + | == CharacterBlockedBy == | ||
| + | |||
| + | '''Full definitions''' | ||
| + | * event CharacterBlokedBy((CHARACTERGUID)_Defender, (CHARACTERGUID)_Attacker, (CHARACTERGUID)_AttackerOwner) | ||
| + | |||
| + | '''Description''' | ||
| + | * Thrown when a character blocks an attack from another character. | ||
| + | |||
| + | '''Parameters''' | ||
| + | * _Defender: The character that received/defended the attack. | ||
| + | * _Attacker: The character that attacked the _Defender. | ||
| + | * _AttackerOwner: The character that owns the _Attacker character. | ||
| + | |||
| + | '''Notes''' | ||
| + | * _AttackerOwner can be the same character as _Attacker, _AttackOwner will be different in the case of summoned characters. | ||
| + | |||
| + | See also: ''CharacterMissedBy'' | ||
| + | |||
| + | == CharacterMissedBy == | ||
| + | |||
| + | '''Full definitions''' | ||
| + | * event CharacterMissedBy((CHARACTERGUID)_Defender, (CHARACTERGUID)_Attacker, (CHARACTERGUID)_AttackerOwner) | ||
| + | |||
| + | '''Description''' | ||
| + | * Thrown when a character misses an attack from another character. | ||
| + | |||
| + | '''Parameters''' | ||
| + | * _Defender: The character that received/defended the attack. | ||
| + | * _Attacker: The character that attacked the _Defender. | ||
| + | * _AttackerOwner: The character that owns the _Attacker character. | ||
| + | |||
| + | '''Notes''' | ||
| + | * _AttackerOwner can be the same character as _Attacker, _AttackOwner will be different in the case of summoned characters. | ||
| + | |||
| + | See also: ''CharacterBlockedBy'', ''CharacterCriticalHitBy'' | ||
| + | |||
| + | == Full definitions == | ||
| + | event CharacterCriticalHitBy((CHARACTERGUID)_Defender, (CHARACTERGUID)_Attacker, (CHARACTERGUID)_AttackerOwner) | ||
| + | |||
| + | Description | ||
| + | Thrown when a character receives a critical hit from an attack of another character. | ||
| + | |||
| + | Parameters | ||
| + | _Defender: The character that received/defended the attack. | ||
| + | _Attacker: The character that attacked the _Defender. | ||
| + | _AttackerOwner: The character that owns the _Attacker character. | ||
| + | |||
| + | Notes | ||
| + | _AttackerOwner can be the same character as _Attacker, _AttackOwner will be different in the case of summoned characters. | ||
| + | |||
| + | See also | ||
| + | CharacterBlockedBy | ||
| + | CharacterKilledBy | ||
| + | |||
| + | |||
| + | |||
| + | Full definitions | ||
| + | event CharacterKilledBy((CHARACTERGUID)_Defender, (CHARACTERGUID)_Attacker, (CHARACTERGUID)_AttackerOwner) | ||
| + | |||
| + | Description | ||
| + | Thrown when a character is killed by another character. | ||
| + | |||
| + | Parameters | ||
| + | _Defender: The character that received/defended the attack. | ||
| + | _Attacker: The character that attacked the _Defender. | ||
| + | _AttackerOwner: The character that owns the _Attacker character. | ||
| + | |||
| + | Notes | ||
| + | _AttackerOwner can be the same character as _Attacker, _AttackOwner will be different in the case of summoned characters. | ||
| + | |||
| + | See also | ||
| + | CharacterBlockedBy | ||
| + | CharacterEnteredRegion | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event CharacterEnteredRegion((CHARACTERGUID)_Character, (STRING)_Region) | ||
| + | Description | ||
| + | Thrown when a character enters a level because it was placed there in the editor, it was teleported there via script, or it was created/spawned there via script. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _Character: the character that entered the level/region | ||
| + | _Region: the name of the level/region (as entered in the Levelname property of the Level -> Edit Level Data... menu entry in the editor. | ||
| + | Notes | ||
| + | |||
| + | For characters statically placed in a level using the editor, this event is thrown only once when the level is first entered. It is not thrown again when loading save games from within that level. TODO: check what happens if the players are teleported out of a level and then back into it (never done in DivinityOrigins mod). | ||
| + | See also | ||
| + | |||
| + | / | ||
| + | CharacterSawCharacter | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event CharacterSawCharacter((CHARACTERGUID)_Character, (CHARACTERGUID)_OtherCharacter) | ||
| + | Description | ||
| + | Thrown when one _Character sees _OtherCharacter. Note that this event is only thrown if _Character has been registered as an event generator. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _Character: the character that does the seeing. | ||
| + | _OtherCharacter: the character that is seen | ||
| + | Notes | ||
| + | |||
| + | By default, only player-controlled characters are event generators. Once you call CharacterCanSee with an NPC as first parameter, an event generator is also registered for this NPC and it will also start throwing CharacterSawCharacter events. This event generator may only work temporarily though, so in general only rely on these events be thrown for player characters. | ||
| + | See also | ||
| + | |||
| + | CharacterCanSee | ||
| + | CharacterLostSightOfCharacter | ||
| + | CharacterStoppedUsingItem | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event CharacterStoppedUsingItem((CHARACTERGUID)_Character, (ITEMGUID)_Item) | ||
| + | Description | ||
| + | Thrown when a character stopped using an item, or if a character tried to use an item and failed. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _Character: the character that used or tried to use _Item. | ||
| + | _Item: the item that was used or attempted to be used | ||
| + | Notes | ||
| + | |||
| + | / | ||
| + | See also | ||
| + | |||
| + | / | ||
| + | CombatStarted | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event CombatStarted((INTEGER)_CombatID) | ||
| + | Description | ||
| + | Thrown once a new combat has started and has been completely initialised. I.e., all initial participants have been added, and combat is ready to start. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _CombatID: A handle that identifies the combat. Should always be > 0. | ||
| + | Notes | ||
| + | |||
| + | This event can also be thrown for an ongoing combat after one or more participants left. In this case, first a new ObjectEnteredCombat event will be thrown for every participant still in the combat, followed by a new CombatStartedEvent with the same _CombatID as before. During these new ObjectEventeredCombat events and CombatStarted event, the combat must again be considered to be not completely initialised yet. | ||
| + | This event will also be thrown when two combats are merged. | ||
| + | See also | ||
| + | |||
| + | ObjectEnteredCombat | ||
| + | ObjectLeftCombat | ||
| + | DialogStartRequested | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event DialogStartRequested((GUIDSTRING)_Target,(GUIDSTRING)_Player) | ||
| + | Description | ||
| + | Thrown whenever a player tries to start a conversation with another object. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _Target: The object to which the conversation request is directed. | ||
| + | _Player: The player that initiated the conversation | ||
| + | Notes | ||
| + | |||
| + | Do not use this event directly. Overload PROC_GLOBAL_DialogStartRequested or PROC_GLOBAL_DialogStartRequested_AfterGenerics instead, so that certain common behaviours are guaranteed to hold in all cases. | ||
| + | This event can only be thrown if the target can accept dialog requests, i.e. if SetHasDialog(_Target,1) is currently active. | ||
| + | See also | ||
| + | |||
| + | SetHasDialog | ||
| + | helper PROC_GLOBAL_DialogStartRequested | ||
| + | helper PROC_GLOBAL_DialogStartRequested_AfterGenerics | ||
| + | GameStarted | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event GameStarted((String)_LevelName, (INTEGER)_IsEditorMode) | ||
| + | Description | ||
| + | Thrown when a level has been loaded and is ready at both the server and client side. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _LevelName: The identifier name of the level that has been loaded | ||
| + | _IsEditorMode: Indicates whether the game is run in the editor or not | ||
| + | Notes | ||
| + | |||
| + | The logic of Osiris is split into a server and a client side, even in single player mode. Some important things that run on the client side are visual effects and physics. | ||
| + | An example of something that is done only when the client side is ready, is playing the effect of the source collars on the characters in the tutorial and Fort Joy levels (since they're visual effects, and hence do not work if started when only the server side is ready) | ||
| + | See RegionStarted for an event that is thrown when the level is ready on the server side. | ||
| + | This event is also thrown when loading a savegame, so add additional logic for code that should be executed only the first time when this level is started (or trigger it from the INIT section of a story goal instead). | ||
| + | See also | ||
| + | |||
| + | RegionStarted | ||
| + | ObjectEnteredCombat | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event ObjectEnteredCombat((GUIDSTRING)_Object, (INTEGER)_CombatID) | ||
| + | Description | ||
| + | Thrown when an object (character or item) enters a combat. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _Object: The object that has entered the combat | ||
| + | _CombatID: A handle that identifies the combat. Should always be > 0. | ||
| + | Notes | ||
| + | |||
| + | This can be a combat that is still being set up, or an existing combat joined by a character that wandered too close. | ||
| + | If the combat is still being set up, not all information may be available yet (e.g., other initial objects may still be added after this one), and you cannot use APIs such as JumpToTurn yet. If you wish to perform some action when a combat has completely started, use CombatStarted instead. | ||
| + | See also | ||
| + | |||
| + | CombatStarted | ||
| + | ObjectLeftCombat | ||
| + | ObjectFlagSet | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event ObjectFlagSet((STRING)_FlagName, (GUIDSTRING)_Speaker, (INTEGER)_DialogInstance) | ||
| + | Description | ||
| + | Thrown when the flag _FlagName is set on object _Speaker in the context indicated by _DialogInstance. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _FlagName: The flag that is set. | ||
| + | _Speaker: The object on which the (character) flag is set. | ||
| + | _DialogInstance: If the flag was set using a dialog node, _DialogInstance contains the dialog's instance ID. If the flag was set from story, _DialogInstance will contain whatever was passed as last parameter to ObjectSetFlag. If the flag was set from behaviour script, DialogInstance will be zero. | ||
| + | Notes | ||
| + | |||
| + | / | ||
| + | See also | ||
| + | |||
| + | ObjectSetFlag | ||
| + | ObjectClearFlag | ||
| + | ObjectLeftCombat | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event ObjectLeftCombat((GUIDSTRING)_Object, (INTEGER)_CombatID) | ||
| + | Description | ||
| + | Thrown when an object (character or item) leaves a combat. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _Object: The object that has left the combat | ||
| + | _CombatID: A handle that identifies the combat. Should always be > 0. | ||
| + | Notes | ||
| + | |||
| + | Reasons why characters may leave combat is because they died, because they got too far from the other participants, or because story forced them to leave. | ||
| + | See also | ||
| + | |||
| + | CombatStarted | ||
| + | ObjectEnteredCombat | ||
| + | ObjectSourcePointAddRequest | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event ObjectSourcePointAddRequest((GUIDSTRING)_Target, (INTEGER)_Amount) | ||
| + | Description | ||
| + | Thrown for every attempt to add source to an object, even if the object cannot hold more source. It is thrown before the source has been added. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _Target: The object to which source gets added. In case of a character, this means there is an attempt to add source points. In case of an item, this means there is an attempt to add charges. | ||
| + | _Amount: The number of source points/charges that is being added. | ||
| + | Notes | ||
| + | |||
| + | As mentioned in the description, this is triggered even when _Target currently already holds its maximum of source. | ||
| + | See also | ||
| + | |||
| + | / | ||
| + | RegionStarted | ||
| + | |||
| + | Full definitions | ||
| + | |||
| + | event RegionStarted((String)_LevelName) | ||
| + | Description | ||
| + | Thrown when the level has been loaded and is ready at the server side, but not yet at the client side. | ||
| + | |||
| + | Parameters | ||
| + | |||
| + | _LevelName: The identifier name of the level that has been loaded | ||
| + | Notes | ||
| + | |||
| + | See GameStarted for usage information that also applies to this call. | ||
| + | See also | ||
| + | |||
| + | GameStarted | ||
Latest revision as of 14:24, 2 August 2017
Events
Events are a way for Osiris to inform script that something happened. All event parameters have [in] semantics.
CharacterBlockedBy
Full definitions
- event CharacterBlokedBy((CHARACTERGUID)_Defender, (CHARACTERGUID)_Attacker, (CHARACTERGUID)_AttackerOwner)
Description
- Thrown when a character blocks an attack from another character.
Parameters
- _Defender: The character that received/defended the attack.
- _Attacker: The character that attacked the _Defender.
- _AttackerOwner: The character that owns the _Attacker character.
Notes
- _AttackerOwner can be the same character as _Attacker, _AttackOwner will be different in the case of summoned characters.
See also: CharacterMissedBy
CharacterMissedBy
Full definitions
- event CharacterMissedBy((CHARACTERGUID)_Defender, (CHARACTERGUID)_Attacker, (CHARACTERGUID)_AttackerOwner)
Description
- Thrown when a character misses an attack from another character.
Parameters
- _Defender: The character that received/defended the attack.
- _Attacker: The character that attacked the _Defender.
- _AttackerOwner: The character that owns the _Attacker character.
Notes
- _AttackerOwner can be the same character as _Attacker, _AttackOwner will be different in the case of summoned characters.
See also: CharacterBlockedBy, CharacterCriticalHitBy
Full definitions
event CharacterCriticalHitBy((CHARACTERGUID)_Defender, (CHARACTERGUID)_Attacker, (CHARACTERGUID)_AttackerOwner)
Description Thrown when a character receives a critical hit from an attack of another character.
Parameters _Defender: The character that received/defended the attack. _Attacker: The character that attacked the _Defender. _AttackerOwner: The character that owns the _Attacker character.
Notes _AttackerOwner can be the same character as _Attacker, _AttackOwner will be different in the case of summoned characters.
See also CharacterBlockedBy CharacterKilledBy
Full definitions event CharacterKilledBy((CHARACTERGUID)_Defender, (CHARACTERGUID)_Attacker, (CHARACTERGUID)_AttackerOwner)
Description Thrown when a character is killed by another character.
Parameters _Defender: The character that received/defended the attack. _Attacker: The character that attacked the _Defender. _AttackerOwner: The character that owns the _Attacker character.
Notes _AttackerOwner can be the same character as _Attacker, _AttackOwner will be different in the case of summoned characters.
See also CharacterBlockedBy CharacterEnteredRegion
Full definitions
event CharacterEnteredRegion((CHARACTERGUID)_Character, (STRING)_Region) Description Thrown when a character enters a level because it was placed there in the editor, it was teleported there via script, or it was created/spawned there via script.
Parameters
_Character: the character that entered the level/region _Region: the name of the level/region (as entered in the Levelname property of the Level -> Edit Level Data... menu entry in the editor. Notes
For characters statically placed in a level using the editor, this event is thrown only once when the level is first entered. It is not thrown again when loading save games from within that level. TODO: check what happens if the players are teleported out of a level and then back into it (never done in DivinityOrigins mod). See also
/ CharacterSawCharacter
Full definitions
event CharacterSawCharacter((CHARACTERGUID)_Character, (CHARACTERGUID)_OtherCharacter) Description Thrown when one _Character sees _OtherCharacter. Note that this event is only thrown if _Character has been registered as an event generator.
Parameters
_Character: the character that does the seeing. _OtherCharacter: the character that is seen Notes
By default, only player-controlled characters are event generators. Once you call CharacterCanSee with an NPC as first parameter, an event generator is also registered for this NPC and it will also start throwing CharacterSawCharacter events. This event generator may only work temporarily though, so in general only rely on these events be thrown for player characters. See also
CharacterCanSee CharacterLostSightOfCharacter CharacterStoppedUsingItem
Full definitions
event CharacterStoppedUsingItem((CHARACTERGUID)_Character, (ITEMGUID)_Item) Description Thrown when a character stopped using an item, or if a character tried to use an item and failed.
Parameters
_Character: the character that used or tried to use _Item. _Item: the item that was used or attempted to be used Notes
/ See also
/ CombatStarted
Full definitions
event CombatStarted((INTEGER)_CombatID) Description Thrown once a new combat has started and has been completely initialised. I.e., all initial participants have been added, and combat is ready to start.
Parameters
_CombatID: A handle that identifies the combat. Should always be > 0. Notes
This event can also be thrown for an ongoing combat after one or more participants left. In this case, first a new ObjectEnteredCombat event will be thrown for every participant still in the combat, followed by a new CombatStartedEvent with the same _CombatID as before. During these new ObjectEventeredCombat events and CombatStarted event, the combat must again be considered to be not completely initialised yet. This event will also be thrown when two combats are merged. See also
ObjectEnteredCombat ObjectLeftCombat DialogStartRequested
Full definitions
event DialogStartRequested((GUIDSTRING)_Target,(GUIDSTRING)_Player) Description Thrown whenever a player tries to start a conversation with another object.
Parameters
_Target: The object to which the conversation request is directed. _Player: The player that initiated the conversation Notes
Do not use this event directly. Overload PROC_GLOBAL_DialogStartRequested or PROC_GLOBAL_DialogStartRequested_AfterGenerics instead, so that certain common behaviours are guaranteed to hold in all cases. This event can only be thrown if the target can accept dialog requests, i.e. if SetHasDialog(_Target,1) is currently active. See also
SetHasDialog helper PROC_GLOBAL_DialogStartRequested helper PROC_GLOBAL_DialogStartRequested_AfterGenerics GameStarted
Full definitions
event GameStarted((String)_LevelName, (INTEGER)_IsEditorMode) Description Thrown when a level has been loaded and is ready at both the server and client side.
Parameters
_LevelName: The identifier name of the level that has been loaded _IsEditorMode: Indicates whether the game is run in the editor or not Notes
The logic of Osiris is split into a server and a client side, even in single player mode. Some important things that run on the client side are visual effects and physics. An example of something that is done only when the client side is ready, is playing the effect of the source collars on the characters in the tutorial and Fort Joy levels (since they're visual effects, and hence do not work if started when only the server side is ready) See RegionStarted for an event that is thrown when the level is ready on the server side. This event is also thrown when loading a savegame, so add additional logic for code that should be executed only the first time when this level is started (or trigger it from the INIT section of a story goal instead). See also
RegionStarted ObjectEnteredCombat
Full definitions
event ObjectEnteredCombat((GUIDSTRING)_Object, (INTEGER)_CombatID) Description Thrown when an object (character or item) enters a combat.
Parameters
_Object: The object that has entered the combat _CombatID: A handle that identifies the combat. Should always be > 0. Notes
This can be a combat that is still being set up, or an existing combat joined by a character that wandered too close. If the combat is still being set up, not all information may be available yet (e.g., other initial objects may still be added after this one), and you cannot use APIs such as JumpToTurn yet. If you wish to perform some action when a combat has completely started, use CombatStarted instead. See also
CombatStarted ObjectLeftCombat ObjectFlagSet
Full definitions
event ObjectFlagSet((STRING)_FlagName, (GUIDSTRING)_Speaker, (INTEGER)_DialogInstance) Description Thrown when the flag _FlagName is set on object _Speaker in the context indicated by _DialogInstance.
Parameters
_FlagName: The flag that is set. _Speaker: The object on which the (character) flag is set. _DialogInstance: If the flag was set using a dialog node, _DialogInstance contains the dialog's instance ID. If the flag was set from story, _DialogInstance will contain whatever was passed as last parameter to ObjectSetFlag. If the flag was set from behaviour script, DialogInstance will be zero. Notes
/ See also
ObjectSetFlag ObjectClearFlag ObjectLeftCombat
Full definitions
event ObjectLeftCombat((GUIDSTRING)_Object, (INTEGER)_CombatID) Description Thrown when an object (character or item) leaves a combat.
Parameters
_Object: The object that has left the combat _CombatID: A handle that identifies the combat. Should always be > 0. Notes
Reasons why characters may leave combat is because they died, because they got too far from the other participants, or because story forced them to leave. See also
CombatStarted ObjectEnteredCombat ObjectSourcePointAddRequest
Full definitions
event ObjectSourcePointAddRequest((GUIDSTRING)_Target, (INTEGER)_Amount) Description Thrown for every attempt to add source to an object, even if the object cannot hold more source. It is thrown before the source has been added.
Parameters
_Target: The object to which source gets added. In case of a character, this means there is an attempt to add source points. In case of an item, this means there is an attempt to add charges. _Amount: The number of source points/charges that is being added. Notes
As mentioned in the description, this is triggered even when _Target currently already holds its maximum of source. See also
/ RegionStarted
Full definitions
event RegionStarted((String)_LevelName) Description Thrown when the level has been loaded and is ready at the server side, but not yet at the client side.
Parameters
_LevelName: The identifier name of the level that has been loaded Notes
See GameStarted for usage information that also applies to this call. See also
GameStarted
