Osiris API Tips Events

From Divinity Engine Wiki
Revision as of 14:23, 2 August 2017 by Larian octaaf (talk | contribs)
Jump to: navigation, search

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