INIT
     USING SHARED Base
     CHARACTER:__Me
     CHARACTER:%AnotherCharacter=null
     FLOAT3:%CurrentPosition=null
     EXTERN INT:%CanRun=1

If you want to override a specific reaction, event, or scriptframe you have to specify this with the OVERRIDE keyword:

REACTION TestReaction, 5 OVERRIDE
EVENT TestEvent OVERRIDE
SCRIPTFRAME TestFrame OVERRIDE

If needed, you can also only inherit specific reactions, events, orscriptframes:

USING ScriptName REACTION ReactionName,NewPriority
USING ScriptName EVENT EventName
USING ScriptName SCRIPTFRAME ScriptFrameName

BEHAVIOUR

This section contains the actual behaviour of the object. It solely consists of a whole bunch of reactions, of which only 1 reaction can be active at the same time. The current reaction gets selected based on its priority and its CHECK. The priority defines how much it wants to be executed and the CHECK decided whether its possible to be executed. The reaction with the highest priority whose CHECK succeeds will be selected for execution:

• The whole list of reactions is always sorted from HIGH to LOW priorities.
• We then check in that order all the reactions with a higher priority of the current reaction and see if their CHECK succeeds.
• As soon as a higher priority reaction's CHECK succeeds, it interrupts the current reaction and will start executing.

Important note: only the CHECKs of higher priority reactions are evaluated every frame. This means that the current reaction's CHECK is NOT reevaluated while it's executing! It could become invalid during the execution. This is also true when calling Reset(): execution simply restarts at the beginning of the current reaction without evaluating the CHECK conditions again.

On top of the priority and CHECKs there's also the USAGE keyword. A reaction needs to specify a USAGE context. You can pick the following USAGE contexts:

• USAGE COMBAT: can only be executed during combat when its the turn of the object
• USAGE WAITING: can only be executed during combat when waiting for its turn
• USAGE PEACE: can only be executed when not in combat
• USAGE ALL: can always be executed

A reaction can have its own local variables. These variables have to start with an underscore and can only be accessed within the reaction itself.

As soon as a reaction is interrupted, the INTERRUPT event will be called immediately and you can execute some code to for example Reset the reaction. You can catch all INTERRUPTS or only specific interrupts (like the movement failed interrupt) and execute actions on the interrupt. If you catch a specific interrupt event you have the possibility to fill in variables for the event:

• An underscore ('_'): this variable is not relevant for the event, it will not prevent the event from firing
• A constant (e.g. "TestString") or a global variable: the variable has to be equal to this constant, otherwise the event will not be executed
• A local variable: this variable will get filled with the variable from the event

Some examples:

OnEnteredCombat(__Me, _) // Only catch the event when __Me entered combat, the second variable one is irrelevant
OnEnteredCombat(_, %GlobalItemVariable) // Only catch the event when %GlobalItemVariable entered combat, the first variable is irrelevant
OnEnteredCombat(_LocalCharacterVariable, _) // Always catches the event, and _LocalCharacterVariable contains the character that entered combat. BEWARE: _LocalCharacterVariable can be null if an item entered combat

The actions during an interrupt are limited to immediate/simple actions, which can be executed immediately (e.g. CharacterMoveTo() is not allowed). Keep in mind though that a reaction can be interrupted for many reasons:

• Higher priority reaction takes over.
• Other system takes over: statuses/dialog/story
• An exception was thrown in the script: e.g. pathfinding failed, ...
• The object got culled (more details on culling can be found later on this page)

Important note: if a reaction gets interrupted and later gets resumed, it will continue executing where it got interrupted! (unless "Reset" was called in the INTERRUPT handler, in which case it will begin from the start again)

An example BEHAVIOUR section:

BEHAVIOUR
REACTION TestReaction, 5 // Priority 5
USAGE PEACE
VARS
     CHARACTER:_TestCharacter
CHECK "(c1|!c2)&!c3" // Reaction can be executed when one of the first 2 conditions passes, and the third condition doesn't pass
     IsInSurface(__Me, SurfaceOil)
     IsInDangerousSurface(__Me)
     CharacterIsFloating(__Me)
ACTIONS
     CharacterFleeFromSurface()
INTERRUPT
ON
     OnMovementFailed(_) // Only when interrupted by a failed movement
ACTIONS
     Reset()

STORY

There are specific story "reactions" called scriptframes. These are almost exactly the same as reactions, but they don't have a priority or CHECK block. They are managed by Story (Osiris) and can be SET or INJECTED. We keep a stack of all currently set scriptframes. If something is on the stack, the current REACTION always gets interrupted! The stack is the highest priority and comes before BEHAVIOUR reactions! Example of stack behaviour:

• When you push something, it is put on the top of the stack.
• When you pop, the top scriptframe is removed (happens when it finished executing)

In our case:
If you SET a scriptframe the stack gets cleared (Abort!) and the new scriptframe gets pushed on the stack.
If you INJECT a scriptframe, it will just push a copy of it on the stack. You can keep injecting the same scriptframe on the stack and it will be executed multiple times.
As soon as the TOP scriptframe is finished, it pops from the stack and the one below it starts/resumes executing.

Just like with reactions, if you INJECT a new scriptframe and there was already a scriptframe on the stack active, it will get interrupted and later resume where it was before. The syntax for writing a SCRIPTFRAME is exactly the same as a REACTION (except for the lack of priority and CHECK, and the fact that they need to be in the STORY section).

EVENTS

This section contains all the events that we want to catch. Events are always immediately and completely executed! It cannot take multiple frames: it's a blocking call and will execute and return immediately when it's done. Even when the object is culled or offstage will it execute its events. Events are always thrown to all objects in the current level. An event can be thrown from code, osiris, or from script itself.
In a reaction or scriptframe, each frame only 1 action gets executed at most. Let's take a piece of script from a REACTION:

Set(%TargetPos,%Enemy)
CharacterEvent(%Enemy,"Attack!") 
CharacterMoveTo(%TargetPos)

In the example above, the first 2 lines will take 2 frames (1 frame per line). The third one will take as long as it takes for the character to move to the target position. However, in an event the actions get executed immediately. Even if it was 100 actions with IFs and WHILEs, it would be executed as it was 1 action. For that reason, you cannot use actions in events that need time (Sleep, CharacterMoveTo, ...). Additionally, the number of actions an event can execute is limited. If you exceed the limit, Osiris will log an error and exit the event. In fact, let me amaze you even more. If you throw a CharacterEvent in an event, that spawns a new event and is thrown on every character and item... even all those events are executed immediately before it gets to the next line.

Just like INTERRUPTs in REACTIONs, EVENTs have to react on something (INTERRUPTs can and EVENTs must). The syntax is equal as well (more information on the event variables can be found in the REACTION INTERRUPT section).
An example EVENTS section:

EVENT TestInitEvent
ON
     OnInit()
ACTIONS
     IF "!c1"
          IsEqual(%Archetype,null)
     THEN
          CharacterSetArchetype(__Me,%Archetype)
          Set(%Archetype,null)
     ENDIF

Lists

Lists are a special parameter type and contain multiple parameters of a single type.

Important note: Lists are more convenient, but they are slower than normal parameters. They also have a limited size, so don't try to fill them with thousands of entries.

Declaring a list:

LIST<INT>:%TestListInt // Fine
LIST<CHARACTER>:%TestListCharacter // Fine
LIST<LIST<INT>>:%TestListNested // Error, can't nest lists

Adding entries:

ListAdd(%TestListInt, 0) // Fine
ListAdd(%TestListInt, {0;1;2}) // Error, trying to add a FLOAT3 to an INT LIST

Removing entries: indices start at 1, and end at the list size. All entries after the removed entry will be shifted to the left:

ListRemove(%TestListInt, 1) // Fine, assuming that the list has 1 or more entries
ListRemove(%TestListInt, 0) // Error, invalid index

Setting or getting entries:

ListSet(%TestListInt, 1, %AnInt) // Fine
ListGet(%TestListInt, 1, %AnInt)

ListSet(%TestListInt, 1, %ACharacter) // Error, trying to set a CHARACTER in an INT LIST
ListGet(%TestListInt, 1, %ACharacter)

ListSet(%TestListInt, 0, %AnInt) // Error, invalid index
ListGet(%TestListInt, 0, %AnInt)

Getting the list size:

ListGetSize(%TestList, %ListSize)

Clearing a list:

ListClear(%TestList)

Important note: Lists currently do not support EXTERN, constants, and STRING , meaning that the following lines will not work in scripts and result in an error during script build:

LIST<INT>:%TestList = {1, 2, 3, 4, 5} // Using a constant to initialize
ListGetSize({1, 2, 3, 4}, %ListSize) // Using a constant in an action call
EXTERN LIST<INT>:%TestList = {1, 2} // Using EXTERN and using a constant to initialize
LIST<STRING>:%TestString // Using STRING as the type

Important Events

OnInit and OnShutDown

OnInit is called each time on all objects in the level when the level is loaded, and OnShutdown is called when the level is unloaded. This would be the place where you can create/destroy your looping effects that should always be on the object.

OnLoaded

OnLoaded is called when the savegame is loaded or when the levelcache is loaded (levelswap). The version of the savegame is passed so you can do your patching "hacks" if necessary.

Interrupts

Interrupts are only called on reactions and can only be caught on that reaction:

• OnBetterReactionFound: a higher priority reaction succeeded its check
• OnNoReactionFound: no reaction has succeeded its check
• OnScriptDisabled: another system has taken control (dialogs, statuses, story)
• OnManualInterrupt: the Interrupt action itself has caused the interrupt
• OnMovementFailed: pathfinding has failed to find a path to the target
• OnException: a character task has failed