Documentation

Callable functions and data available inside character scripts

A list of functions, data, etc, is created automatically whenever you run the game, in a file on your hard drive. This lists what external code you get "for free" and can call from inside a character script.

Windows: My Documents\Wolfire\Overgrowth\aschar_docs.h

Mac: ~/Library/Application Support/Overgrowth/aschar_docs.h

Linux: ~/.local/share/Overgrowth/aschar_docs.h

This documentation will change with each version of the game, so keep checking back on this aschar_docs.h file to see the most up to date information.

There are also wiki pages which have more detailed documentation many of these functions. These pages have a danger of going out of date, but give more detailed documentation on some of the code:

Init function

Init is called when the character is first to be loaded, upon level load.

Must return true upon success, and false upon failure.

Important things to do in this call are to set the motion object character path, load the character (character_getter.Load(character_path);), read the species tag (character_getter.GetTag("species")), set up the skeleton, etc.

Be careful, this may be called before some objects or script params are present in the level.

SetParameters function

SetParameters is called when the character is first loaded, whenever the script parameter values are changed via the GUI, and whenever Reset() is called.

It is also called when an undo/redo is fired in the editor, to reload script params from that point in history.

This function allows the character script to work with script parameter values.
You can use it to define, change, verify, protect (undo writes), or locally cache script parameter values.

You can also use this to work with game objects that you use character script params to control (if any - this is a trick usually done in hotspot scripts, with placeholder objects, but there isn't any reason why a character script couldn't do similar things, if it was somehow valuable).

ScriptSwap function

ScriptSwap is called before Update(), when the character control script gets swapped (caused by going from player control to AI control, or vice-versa).

This function gives the script an opportunity to properly adjust its variables after the transition to the new script, so updates happen smoothly. Existing global variables are copied over, but variables that aren't shared between the scripts might need to be derived and/or initialized in this function.

Note: The character model, rigged object, etc, stay loaded when this script is swapped, so this is mostly just available to handle special on-swap behavior (if you want to add any).

Note: The update frequency is based on whether the new script is a player control script (Data/Scripts/playercontrol.as, set to update 120-per-second) or an AI control script (any other script, set to update 30-per-second, with a random offset with 120hz frequency to spread out the updates).

Update function

Update is called regularly by the engine so you can perform work. It is only called while the game is unpaused.

It may be useful to do initialization once in this function, if you need objects or character script params to be present.

Be careful to keep this function short, sweet, and fast. Update gets called 120 times a second as of the time of this writing.

Note: The update frequency is based on whether this script is a player control script (Data/Scripts/playercontrol.as, set to update 120-per-second) or an AI control script (any other script, set to update 30-per-second, with a random offset with 120hz frequency to spread out the updates).

ReceiveMessage function

ReceiveMessage is called when messages have been sent to this character by the engine, level, or objects in levels.

Objects in levels (such as hotspots or other characters) can send this using movement_object.SendMessage("some message string");.

Parameters can be sent by separating them with spaces, and putting quotes around parameters that might contain spaces, then using the TokenIterator object. TODO: Write a TokenIterator example and link to it.

Note: If you're setting up the code to send a message to a character, you might want to choose to only send messages to player characters, or non-player characters. TODO: Example of how to do this filtering.

SetEnabled function

This function allows the character to enable or disable any objects that should be associated with the character (such as fire ribbons, sounds, shadow objects, character camera item flashes, and water splashes).

This function can also be used to internally set variables so that its functions have no effect. The engine will generally not call the character if it is not enabled (except when it gets re-enabled), but other scripts could theoretically call functions on the character using movement_object_instance.Execute("some code");.

Note: It may be viable to call Dispose() from inside this function, as long as you're careful not to double-delete things.

ForceApplied function

NOTE: Vestigial function that is not called by the engine, but still required to be present. It could be called by another script, if so desired (via movement_object.ApplyForce(vec3);), but the base game doesn't currently do this. RiggedObject functions are used instead for this purpose, or other collision response callbacks that are more specialized (like HitByItem).

AboutToBeHitByItem function

Called when a character is about to be hit by an item so deflection can be tested/triggered.

Return -1 to specify that the collision was avoided (such as when the character deflects or catches the item). Make sure to handle the result of that avoidance as well inside this function, such as flinging the weapon to the side, or attaching it to the character's hand.

Return 1 to specify that the collision could not be avoided, and the collision handling should continue on. Handle the reactions to this case in the HitByItem() callback, instead of in this function.

HitByItem function

Called when the character is hit by an item so it can react to the impact, take damage, etc.

material: Per-polygon-edge material description for the edge that hit the character, in case the result of impact should be different (less or more damage, sharp vs not sharp, etc). Note that the base game doesn't do anything in response to this value.

point_of_impact: The point where the item impacted the character

item_id: The id of the game object that hit this character

impact_type: 2 = sticks, 1 = cut, 0 = bounce off

Note: Any avoidance of the collision (catching the item, deflecting it, etc) should happen in AboutToBeHitByItem(int) instead.

PreDrawCameraNoCull function

PreDrawCameraNoCull is called for all objects in the scene, to perform per-frame, per-camera functions. Unliked PreDrawCamera, this function is always called, even if the object is culled by occlusion or frustum culling for this camera.

Note: PreDrawCameraNoCull is called for each player character's camera, for cube map probes ("reflection captures"), for shadow cascades, etc. The first call to this function is made after all calls to PreDrawFrame have completed for all objects.

Examples of character-related things this function are useful (in the base scripts) include:

Doing character animation discontinuity fixes

Updating the camera full-screen vignette effects for the character's camera

Setting camera depth-of field for the character's camera

PreDrawCamera function

PreDrawCamera is called for characters in the scene that were not culled out of the view of this camera, in order to perform per-frame, per-camera functions. It is called for each character that didn't get culled immediately after the call to PreDrawCamera. Unlike PreDrawCamera, this function is only called if the character is not culled by occlusion or frustum culling in this camera's view.

Note: PreDrawCamera is called for each player character's camera, for cube map probes ("reflection captures"), for shadow cascades, etc. It may be called more than once per character per frame, since it handles per-camera actions. This is called immediately after PreDrawCameraNoCull was completed for the same object, with the same camera, so calls to these two functions are interleaved.

Examples of character-related things this function are useful (in the base scripts) include:

FinalAnimationMatrixUpdate function

For the base unmodified game scripts, examples include rolling contact with ground and rolling animation transitions, turning torso towards target, planting feet on ground, ledge hanging, tethering when dragging bodies, eye look direction, foot balancing on "balance" collision painted surfaces. It is also called by base game in "FixDiscontinuity"

Note: This function gets triggered at the RiggedObject level, not at the MovementObject level.

HandleAnimationEvent function

Animation events are created by the animation files themselves. For example, when the run animation is played, it calls HandleAnimationEvent("leftrunstep", left_foot_pos) when the left foot hits the ground.

Note: This function gets triggered at the RiggedObject level, not at the MovementObject level.

TODO: List current animation events that are tagged in scripts? Is this system open for adding new items, and do any existing ones require behavior to be implemented, or could they be ignored?

WasBlocked function

Vestigial function not called by the engine or base game scripts. It is exposed to other scripts on the [email protected] interface, and must be present if it gets called by game scripts.

Note: This might be vaguely useful if you're building a full replacement for combat, but considering it takes no parameters, and the WasHit function is flexible enough to support two-pass combat checks and handle blocking, this function might just be entirely unneeded at this point.

Dispose function

Dispose is called when the character is destroyed, either by manually deleting it, or when the level is unloaded.

WARNING: Do not DeleteObjectID for other game objects from this function! If you try to, then the game will likely crash on level unload when calling Dispose() on the object you deleted. Also don't try to QueueDeleteObjectID() through Dispose, or it will really mess with undo/redo state.

This function allows the character to free any non-game objects that are owned by this character (such as fire ribbons, sounds, shadow objects, character camera item flashes, and water splashes).

ResetWaypointTarget function

ResetWaypointTarget is called when a character or path point that this character is directed to follow (connected to) is changed.

This happens when the target gets deleted, this character is disconnected from it, or the connection target is updated to a new target. This can happen either through the editor, or through scripting logic.