Objektscripte

Objektscripte kontrollieren die komplexen Verhaltensweisen eines Objekts. Für eine Beschreibung der Scriptsprache C4Script siehe C4Script-Dokumentation.

Erzeugung

Für jedes Objekt ruft die Engine bei der Erschaffung des Objekts die Funktion Initialize im Objektscript auf.
func Initialize()
{
  CreateContents(Rock);
}
Ein Objekt mit diesem Script enthält sofort nach seiner Erschaffung einen Stein. Die Initialisierungsfunktion wird erst aufgerufen, nachdem das Objekt seine volle Größe erreicht hat. Bei Bauwerken also erst, nachdem sie vollständig gebaut wurden und bei Lebewesen erst, wenn sie voll ausgewachsen sind.

ActMap

Ein aktives Objekt kann außerdem in seiner Aktivitätsdefinition Script-Aufrufe enthalten. Die als StartCall definierte Funktion wird immer dann aufgerufen wird, wenn die Aktivitätsschleife erneut startet. EndCall wird aufgerufen, wenn die Aktivitätsschleife endet. PhaseCall wird bei jedem Animationsschritt aufgerufen (da dies äußerst rechenintensiv ist, sollte PhaseCall nur bei seltenen und kurzzeitig ausgeführten Aktivitäten eingesetzt werden). Die Frequenz der Aufrufe bestimmt sich aus der Aktivitätsgeschwindigkeit.

#include

Ein Objektscript kann auf dem Script eines anderen Objekts basieren:
#include Clonk
At this position the complete script of the specified object definition (that of the clonk, in this case) is inserted, including all scripts that that script includes or got via #appendto. The only exception is that every script is included only once, so including both the Clonk script and a script that is included by the Clonk script doesn't include that script twice. Other Obviously, the included definition must be valid and loaded. Declared functions can be overloaded by functions of the same name that occur later in the script. Also see inherited().

Interaction from other scripts

Other scripts can call functions of an object obj with the -> and ->~ operators.
var obj = CreateObject(Flint); obj->Hit();

Objekt-Calls der Engine

Die Engine ruft zu Zeiten die folgenden Funktionen in Objektscripten auf.
Funktion Parameter Beschreibung
Definition Called in definition context after all definitions have been loaded and before definition properties are frozen. Use this callback to initialize complex definition properties such as EditorProps or dependencies between definitions. Definition() callbacks are performed in descending order of the DefinitionPriority property or 0 if that property is not defined.
Initialize Wenn das Objekt fertiggestellt wird (Con größer gleich 100).
Construction object by_object Wenn das Objekt erzeugt wird. Als Parameter wird das Objekt übergeben, in dem das erzeugende Script steht. Siehe auch Construction
Destruction Wenn das Objekt gelöscht wird.
EditorInitialize Called after Construction and Initialize when the object is placed in the editor.
Hit int x_dir, int y_dir When the object collides with the landscape or is collected at high velocity (>=15). The velocity parameters are provided with precision 100, instead of the default 10.
Hit2 int x_dir, int y_dir Like Hit, with speeds >= 20 (see OCF_HitSpeed2). The velocity parameters are provided with precision 100, instead of the default 10.
Hit3 int x_dir, int y_dir Like Hit, with speeds >= 60 (see OCF_HitSpeed3). The velocity parameters are provided with precision 100, instead of the default 10.
Grab object target, bool grab Wenn das Objekt ein anderes Objekt anfasst oder loslässt.
Grabbed object by_object, bool grab Wenn das Objekt durch ein anderes Objekt angefasst oder losgelassen wird.
Get object target Wenn das Objekt ein Objekt aus einem anderen Objekt herausnimmt.
Put Wenn das Objekt ein Objekt in einem anderen Objekt ablegt.
DigOutObject object obj When the object dug out another object that was stuck in solid material or when a new object is created from material during digging.
DugOut object object_by When the object was spawned from dug out material. The object might get removed afterwards if the material has Dig2ObjectCollect=2.
Damage int change, int cause, int by_player Wenn das Objekt beschädigt wird. Siehe Fx*Damage für Werte von cause.
DeepBreath Wenn das Lebewesen nach dem Auftauchen mehr als die Hälfte seiner Atemkapazität auffüllt.
Incineration int by_player Wenn das Objekt entzündet wird. Achtung: Bei Objekten, die ihre Definition mit BurnTo ändern, findet der Aufruf im verbrannten Objekt statt!
IncinerationEx int by_player Wenn das Objekt in einer löschenden Flüssigkeit gesprengt, und damit nicht angezündet wird. Aufruf analog zu Incineration.
Death Wenn ein Lebwesen stirbt.
Activate object by_object Aktivierung durch einen Doppelklick auf Graben. Nur getragene Objekte und direkt spielergesteuerte Objekte. Wird aufgerufen, nachdem die interne Befehlskette (z.B. Bäume fällen) abgearbeitet wurde.
Contact_ Wenn das Objekt die Landschaft berührt. Siehe CNAT - Contact Attachment.
Control_ object by_object Wenn das Objekt von außen gesteuert wird. Siehe Control-Funktionen.
Contained_ object by_object Wenn das Objekt von innen gesteuert wird. Siehe Control-Funktionen.
ControlCommand string command, object target, int x, int y, object target2, int data, object command_object Wenn dem Objekt durch den Spieler ein selbständig auszuführender Befehl gegeben wurde. Siehe Control-Funktionen.
ControlCommandFinished string command, object target, int x, int y, object target2, any Data Wenn das Objekt einen selbständigen auszuführenden Befehl vollendet hat oder die Ausführung des Befehls fehlgeschlagen ist.
ControlTransfer object obj, int x, int y Wenn ein durch die Wegfindungsroutine gesteuertes Objekt (obj) die Transferzone dieses Objekts zum Zielpunkt x/y passieren möchte. Die Transferfunktion kann dem Objekt entsprechende Kommandos geben und sollte bei erfolgreicher Bearbeitung true zurückliefern. Siehe auch SetTransferZone().
OnSynchronized Wenn ein Objekt geladen oder synchronisiert wird. Objekte mit einer TransferZone sollten diese bei jedem Aufruf von OnSynchronized neu setzen. Siehe auch SetTransferZone().
IsFulfilled Nur bei Spielziel-Objekten. Bei Rückgabewert true ist das Spielziel erfüllt.
ControlContents id target Wenn ein neues Inhaltsobjekt angewählt wird. Siehe Control-Funktionen.
Selection object container Wenn das Objekt durch einen Inventarwechsel ausgewählt wird. Wenn die Funktion abgefangen wird, sollte ein eigener Auswahlsound abgespielt werden.
CatchBlow int level, object by Wenn das Objekt von einem anderen Objekt geschlagen oder getroffen wird.
QueryCatchBlow object by Bevor das Objekt von einem anderen Objekt geschlagen oder getroffen wird. Wenn QueryCatchBlow true zurückgibt, können damit physikalische Treffer abgefangen werden.
OnLineBreak int cause Wenn ein Leitungsobjekt unterbrochen wird. cause: 0 durch Bewegung, 1 durch fehlendes oder unvollständiges Zielobjekt.
OnLineChange int cause When a line object is changed, that is when one of it vertices changed its position.
AttachTargetLost Wenn das Objekt eine ATTACH-Aktivität besessen hatte, aber das Actiontarget verloren hat. Die Aktivität ist beim Aufruf bereits zurückgesetzt.
CrewSelection bool deselect, bool cursor_only Bei Änderung der Crewauswahl. cursor_only gibt an, ob nur das Mannschaftsmitglied angewählt wurde, welches den Cursor hat.
GetObject2Drop object for_collection_of_object Zur Ermittlung des am wenigsten gebrauchten Objekts, wenn der Clonk versucht, ein neues aufzunehmen. Die Funktion sollte das abzulegende Objekt zurückliefern, oder nil für keins.
OnMenuSelection int index, object menu_object Wenn ein Menueintrag ausgewählt wurde.
CalcValue object in_base, int for_player Ermittelt den Wert eines Objekts. Siehe auch GetValue().
CalcDefValue object in_base, int for_player Ermittelt den Wert eines (noch nicht gekauften) Objekttyps. Siehe auch GetValue().
CalcBuyValue id item, int value Rückgabewert ist Einkaufspreis des Objekttyps.
CalcSellValue object obj, int object_value Rückgabewert ist Verkaufspreis des Objekttyps.
LiftTop Wenn das Objekt bei einer LIFT-Aktivität ein anderes Objekt höher angehoben hat als in der DefCore angegeben.
Stuck Wird aufgerufen, wenn das Ziel einer PUSH- oder LIFT-Aktivität festhängt.
GrabLost Wenn das Ziel einer PUSH- oder PULL-Aktion verloren geht.
Collection object obj, bool put Wenn das Objekt ein anderes Objekt (obj) aufgenommen hat (nur durch einsammeln oder anfassen und ablegen).
Collection2 object obj Wenn das Objekt ein anderes Objekt (obj) aufgenommen hat (immer, auch durch Scriptbefehl Enter)
ContentsDestruction object destroyed Wenn ein Inhaltsobjekt dieses Objekts zerstört wird. Zum Aufrufzeitpunkt existiert das Objekt noch und wird erst danach zerstört.
Departure object container Wenn das Objekt ein anderes Objekt (container) verlassen hat.
Ejection object obj Wenn ein Objekt (obj) dieses Objekt verlassen hat (auch durch Scriptbefehl Exit).
Entrance object container Wenn das Objekt ein anderes Objekt (container) betreten hat.
ActivateEntrance object by_object Wenn ein anderes Objekt versucht, das Objekt durch Entrance zu betreten.
RejectCollect id def, object obj Wird vor Collection aufgerufen. Wenn RejectCollect true zurückgibt, kann damit die Aufnahme des anderen Objekts verhindert werden.
RejectEntrance object into_object Wird vor Entrance aufgerufen. Wenn RejectEntrance true zurückgibt, kann damit das Hineinversetzen in das andere Objekt verhindert werden.
InitializePlayer int player Aufruf in Spielziel, -regel und Umweltobjekten nach der Platzierung eines beitretenden Spielers, und vor dem entsprechenden Aufruf im Szenarioscript.
SellTo int by_player Wenn das Objekt verkauft wird. Rückgabewert nil oder die ID des Objekts, welches dem Heimatbasismaterial hinzugefügt wird.
Sale int by_player Wenn das Objekt verkauft wird.
Purchase int by_player, object buy_object Wenn das Objekt gekauft wird.
Recruitment int player Wenn das Objekt der Crew eines Spielers hinzugefügt wird.
RejectTeamSwitch int player, int new_team Aufruf in Spielziel, -regel und Umweltobjekten und dem Szenarioscript. Wenn RejectTeamSwitch true zurückgibt, kann der Teamwechsel eines Spielers (durch SetPlayerTeam) verhindert werden.
OnTeamSwitch int player, int new_team, int old_team Aufruf in Spielziel, -regel und Umweltobjekten und dem Szenarioscript. Wenn ein Spieler erfolgreich von old_team zu new_team transferiert wurde (durch SetPlayerTeam).
OnCompletionChange int old_con, int new_con Callback in when the completion of the object has changed (see GetCon, DoCon and SetCon).
EditCursorMoved int old_x, int old_y When object is moved in editor. Callback is also done when moved in non-network pause mode. old_x, old_y contains object position before movement.
SaveScenarioObject proplist props Called when scenario is saved from the editor. Object should write creation of itself and properties to the buffer props. Return true if the object should be saved and false if saving of this object should be omitted. See Scenario saving.

Scenario saving

When the user chooses the "Save Scenario" option from the editor menu, the engine calls a global function SaveScenarioObjects defined in System.ocg/SaveScenario.c. This function writes all objects to the Objects.c file in their current state. The function stores all objects except the crew of currently joined human players and objects of a type that starts with GUI_. By default, objects are recreated using a call to CreateObject followed by setting a number of default properties like position, rotation, speed, action, if they are not in their default state.
For most object, the default saving method should be fine. However, it is possible to override the SaveScenarioObject callback to control how objects are created and which properties are set.
For example if a switch wants to save its target which is stored in a local variable called "target", the switch definition can override the callback:
local target;

func SetTarget(object new_target) { target = new_target; return true; }

func SaveScenarioObject(props)
{
	if (!inherited(props, ...)) return false;
	if (target) props->AddCall("Target", this, "SetTarget", target);
	return true;
}
As a result, the generated Objects.c file will include the call to SetTarget if the switch is saved. Dependent objects should always either be passed to the AddCall function or stored as a string from the MakeScenarioSaveName function. If this is done, that object is marked as a dependency. The saving mechanism will ensure that any object this object depends on will be created before. In case of circular dependencies, the object property setting script is detached from object creation script.
If an object should not be saved in scenarios - for example, because it is just the helper of another object - the SaveScenarioObject callback should be overloaded to return false.
The object creation procedure can also be adjusted. For example, the waterfall object (defined in Objects.ocd/Environment.ocd/Waterfall.ocd) is created using the global functions CreateWaterfall and CreateLiquidDrain, which create a Waterfall object and attach an effect to it. To generate the creation functions from the effects, the waterfall overrides SaveScenarioObject:
func SaveScenarioObject(props)
{
	if (!inherited(props, ...)) return false;
	var fx_waterfall = GetEffect("IntWaterfall", this);
	if (fx_waterfall)
	{
		props->RemoveCreation();
		props->Add(SAVEOBJ_Creation, "CreateWaterfall(%d,%d,%d,%v)",fx_waterfall.X, fx_waterfall.Y, fx_waterfall.Strength, fx_waterfall.Material);
	}
	return true;
}
The call to RemoveCreation removes the existing object creation using CreateObject.
If you need access to one of the objects created in the editor, you can set its "StaticSaveVar" property to the name of a static variable. The InitializeObjects() function will then save the object in that variable.
The following table lists standard properties that are saved if their value is different from the default and if it is not removed using a props->Remove call.
Property name Standardwert Beschreibung
Alive true Category C4D_Living only: If object is not alive, a call to SetKill is stored. See GetAlive and Kill.
Action this.DefaultAction Action as retrieved using GetAction and set using SetAction. Includes ActionTargets. Not stored by default but only if SaveScenarioObjectAction is called.
Phase 0 Action phase (see GetPhase and SetPhase). Not stored by default but only if SaveScenarioObjectAction is called.
Dir DIR_Left Animation direction (see GetDir and SetDir)
ComDir COMD_Stop Commanded movement direction (see GetComDir and SetComDir)
Con 100 Construction percentage, i.e. object size (see GetCon and SetCon)
Category GetID()->GetCategory() Object category (see GetCategory and SetCategory)
R 0 Rotation (see GetR and SetR)
XDir 0 Horizontal speed (see GetXDir and SetXDir)
YDir 0 Vertical speed (see GetYDir and SetYDir). Vertical speed is not saved it is very small and the object touches the ground to avoid saving of speed on idle objects.
RDir 0 Rotation speed (see GetRDir and SetRDir)
Color 0, 0xffffffff Object color of ColorByOwner-surfaces (see GetColo and SetColor)
ClrModulation 0, 0xffffffff Object color modulation of all surfaces (see GetClrModulation and SetClrModulation)
BlitMode 0 Object drawing mode (see GetObjectBlitMode and SetObjectBlitMode)
MeshMaterial GetID()->GetMeshMaterial() Custom assignments of mesh materials (see GetMeshMaterial and SetMeshMaterial)
Name GetID()->GetName() Object name (see GetName and SetName)
MaxEnergy GetID().MaxEnergy Maximum energy (see Properties)
Energy GetID().MaxEnergy/1000 Current energy level (see GetEnergy and DoEnergy)
Visibility VIS_All Object visibility (see Properties)
Plane GetID().Plane Object plane, i.e. z-order (see Properties)
Position Object position. This is only set if the object has a rotation and could not be created directly at the correct offset (see SetPosition)
Command None Stores only the topmost command of the chain (see GetCommand and SetCommand)
Fire Fire effect.
Properties published to the editor as EditorProps can also be saved automatically by setting the Save property of the EditorProp to a string that serves as an identifier so saved properties can be removed by derived definitions. These properties are atuomatically saved if they are different from their default value. E.g.:
/* Define two properties that can be set in the editor */
// foo is a property with a setter function
local foo = 42;
public func SetFoo(new_foo) { foo = new_foo; return true; }

// bar is just a property without setter
local bar = 23;

local EditorProps = {
  foo = { Type="int", Set="SetFoo", Save="Foo" }; // saved as object->SetFoo(value); unless foo is 42.
  bar = { Type="int", Save="Bar"; } // saved as object.bar = value; unless bar is 23.
};
By default, effects are not saved in scenarios. To force saving of an effect, define the Fx*SaveScen callback. For example, the fire effect saves itself like this:
global func FxFireSaveScen(object obj, proplist fx, proplist props)
{
	// this is burning. Save incineration to scenario.
	props->AddCall("Fire", obj, "Incinerate", fx.strength, fx.caused_by, fx.blasted, fx.incinerating_object);
	return true;
}
obj and fx refer to the object and effect proplist as for any effect call. save_name is the variable name of the effected object and is unset for global effects.

Scenario saving reference

The following functions are available to call on the "props" parameter passed to SaveScenarioObject callbacks:

AddCall

bool AddCall(string id, object target, string function, any par1, any par2, ...);
Adds a new call of format target->Function(par1, par2, ...) to the stored object script. Object parameters may be passed as is; strings must be quoted explicitely.
The id parameter is an identifier which can be used by derived objects to remove the property again.

Add

bool AddCall(string id, string script, any par1, any par2, ...);
Adds a custom script snippet of any format. script may contain format characters and parameters are formatted into the string using Format().

Remove

int Remove(string id);
Remove all strings added previously using AddCall or Add with the given ID. Can also be used to remove default properties. Returns number of script lines removed.

RemoveCreation

bool RemoveCreation();
Remove all strings added previously using with IDs SAVEOBJ_Creation or SAVEOBJ_ContentsCreation.

Clear

bool Clear();
Remove all creation and property setting strings.
sulai, 2003-11
matthes, 2004-07
Clonkonaut, 2008-04
Sven2, 2013-12
Marky, 2019-07