go3 changed
Game object API documentation
Functions
go.animate(3 overloads)<P>(): <K extends AnimatableKey<P>>(url: SceneAddress | Hash | Url, property: K, playback: go.Playback, to: AnimateTarget<P[K]>, easing: Vector | go.Easing, duration: number, ...rest: [] | [delay: number, complete_function?: (self: unknown, url: Url, property: Hash) => void]) => void<R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K, playback: go.Playback, to: PropertyAnimateTo<AddressCatalog<R>["catalog"], K>, easing: Vector | go.Easing, duration: number): void<R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K, playback: go.Playback, to: PropertyAnimateTo<AddressCatalog<R>["catalog"], K>, easing: Vector | go.Easing, duration: number, delay: number, complete_function?: (self: unknown, url: Url, property: Hash) => void): void
go.cancel_animations<R extends SceneAddress | Hash | Url, K extends AnimatablePropertyName<AddressCatalog<R>>>(url?: R, property?: K): voidgo.delete(2 overloads): void(id?: SceneGameObjectAddress | Hash | Url | (SceneGameObjectAddress | Hash | Url)[] | LuaPairsIterable<AnyNotNil, SceneGameObjectAddress | Hash | Url> | boolean)(id: SceneGameObjectAddress | Hash | Url | (SceneGameObjectAddress | Hash | Url)[] | LuaPairsIterable<AnyNotNil, SceneGameObjectAddress | Hash | Url>, recursive: boolean)
go.exists(url: SceneGameObjectAddress | Hash | Url): booleango.get(3 overloads)C<P>(): <K extends keyof P>(url: SceneAddress | Hash | Url, property: K, ...options: [] | [GoPropertyOptions]) => P[K]<R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K): PropertyRead<AddressCatalog<R>["catalog"], K><R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K, options: GoPropertyOptions): PropertyRead<AddressCatalog<R>["catalog"], K>
go.get_id(2 overloads): Hashgo.get_parent(id?: SceneGameObjectAddress | Hash | Url): Hash | undefinedgo.get_position(id?: SceneGameObjectAddress | Hash | Url): Vector3go.get_rotation(id?: SceneGameObjectAddress | Hash | Url): Quaterniongo.get_scale(id?: SceneGameObjectAddress | Hash | Url): Vector3go.get_scale_uniform(id?: SceneGameObjectAddress | Hash | Url): numbergo.get_world_position(id?: SceneGameObjectAddress | Hash | Url): Vector3go.get_world_rotation(id?: SceneGameObjectAddress | Hash | Url): Quaterniongo.get_world_scale(id?: SceneGameObjectAddress | Hash | Url): Vector3go.get_world_scale_uniform(id?: SceneGameObjectAddress | Hash | Url): numbergo.get_world_transform(id?: SceneGameObjectAddress | Hash | Url): Matrix4go.property(8 overloads)C(name: string, value: number): ScriptProperty<number>(name: string, value: boolean): ScriptProperty<boolean>(name: string, value: Hash): ScriptProperty<Hash>(name: string, value: Url): ScriptProperty<Url>(name: string, value: Vector3): ScriptProperty<Vector3>(name: string, value: Vector4): ScriptProperty<Vector4>(name: string, value: Quaternion): ScriptProperty<Quaternion>(name: string, value: string): ScriptProperty<string>
go.set(3 overloads)C<P>(): <K extends WritableKey<P>>(url: SceneAddress | Hash | Url, property: K, value: XyWrite<P, K>, ...options: [] | [GoPropertyOptions]) => void<R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K, value: PropertyWrite<AddressCatalog<R>["catalog"], K>): void<R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K, value: PropertyWrite<AddressCatalog<R>["catalog"], K>, options: GoPropertyOptions): void
go.set_parent(id?: SceneGameObjectAddress | Hash | Url, parent_id?: SceneGameObjectAddress | Hash | Url, keep_world_transform?: boolean): voidgo.set_position(position: Vector3, id?: SceneGameObjectAddress | Hash | Url): voidgo.set_rotation(rotation: Quaternion, id?: SceneGameObjectAddress | Hash | Url): voidgo.set_scale(scale: number | Vector3, id?: SceneGameObjectAddress | Hash | Url): voidgo.set_scale_xy(scale: number | Vector3, id?: SceneGameObjectAddress | Hash | Url): voidgo.update_world_transform(id?: SceneGameObjectAddress | Hash | Url): voidgo.world_to_local_position(position: Vector3, url?: SceneGameObjectAddress | Hash | Url): Vector3go.world_to_local_transform(transformation: Matrix4, url?: SceneGameObjectAddress | Hash | Url): Matrix4
go.animate(3 overloads)
This is only supported for numerical properties. If the node property is already being animated, that animation will be canceled and replaced by the new one. If a complete_function (lua function) is specified, that function will be called when the animation has completed. By starting a new animation in that function, several animations can be sequenced together. See the examples for more information. If you call go.animate() from a game object's final() function, any passed complete_function will be ignored and never called upon animation completion. See the properties guide for which properties can be animated and the animation guide for how them.
<P>(): <K extends AnimatableKey<P>>(url: SceneAddress | Hash | Url, property: K, playback: go.Playback, to: AnimateTarget<P[K]>, easing: Vector | go.Easing, duration: number, ...rest: [] | [delay: number, complete_function?: (self: unknown, url: Url, property: Hash) => void]) => void<R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K, playback: go.Playback, to: PropertyAnimateTo<AddressCatalog<R>["catalog"], K>, easing: Vector | go.Easing, duration: number): void<R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K, playback: go.Playback, to: PropertyAnimateTo<AddressCatalog<R>["catalog"], K>, easing: Vector | go.Easing, duration: number, delay: number, complete_function?: (self: unknown, url: Url, property: Hash) => void): voidParameters
url:R— url of the game object or component having the propertyproperty:K— id of the property to animateplayback:go.Playback— playback mode of the animationgo.PLAYBACK_ONCE_FORWARDgo.PLAYBACK_ONCE_BACKWARDgo.PLAYBACK_ONCE_PINGPONGgo.PLAYBACK_LOOP_FORWARDgo.PLAYBACK_LOOP_BACKWARDgo.PLAYBACK_LOOP_PINGPONG
to:PropertyAnimateTo<AddressCatalog<R>["catalog"], K>— target property valueeasing:Vector | go.Easing— easing to use during animation. Either specify a constant, see the animation guide for a complete list, or a vmath.vector with a curveduration:number— duration of the animation in secondsdelay:number— delay before the animation starts in secondscomplete_function?:(self: unknown, url: Url, property: Hash) => void— optional function to call when the animation has completedselfscript_instance The current script instance.urlurl The game object or component instance for which the property is animated.propertyhash The id of the animated property.
Animate the position of a game object to x = 10 during 1 second, then y = 20 during 1 second:
go.animate(go.get_id(), "position.x", go.PLAYBACK_ONCE_FORWARD, 10, go.EASING_LINEAR, 1, 0, () => {
go.animate(go.get_id(), "position.y", go.PLAYBACK_ONCE_FORWARD, 20, go.EASING_LINEAR, 1);
});local function x_done(self, url, property)
go.animate(go.get_id(), "position.y", go.PLAYBACK_ONCE_FORWARD, 20, go.EASING_LINEAR, 1)
end
function init(self)
go.animate(go.get_id(), "position.x", go.PLAYBACK_ONCE_FORWARD, 10, go.EASING_LINEAR, 1, 0, x_done)
endAnimate the y position of a game object using a crazy custom easing curve:
const values = [
0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1,
];
const vec = vmath.vector(values);
go.animate("go", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, vec, 2.0);local values = { 0, 0, 0, 0, 0, 0, 0, 0,
1, 1, 1, 1, 1, 1, 1, 1,
0, 0, 0, 0, 0, 0, 0, 0,
1, 1, 1, 1, 1, 1, 1, 1,
0, 0, 0, 0, 0, 0, 0, 0,
1, 1, 1, 1, 1, 1, 1, 1,
0, 0, 0, 0, 0, 0, 0, 0,
1, 1, 1, 1, 1, 1, 1, 1 }
local vec = vmath.vector(values)
go.animate("go", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, vec, 2.0)go.cancel_animations<R extends SceneAddress | Hash | Url, K extends AnimatablePropertyName<AddressCatalog<R>>>(url?: R, property?: K): void
By calling this function, all or specified stored property animations of the game object or component will be canceled. See the properties guide for which properties can be animated and the animation guide for how to animate them.
Cancel the animation of the position of a game object:
go.cancel_animations(go.get_id(), "position");go.cancel_animations(go.get_id(), "position")Cancel all property animations of the current game object:
go.cancel_animations(".");go.cancel_animations(".")Cancel all property animations of the sprite component of the current game object:
go.cancel_animations("#sprite");go.cancel_animations("#sprite")Parameters
url?:string | Hash | Url— url of the game object or componentproperty?:string | Hash— optional id of the property to cancel
go.delete(2 overloads): void
Delete one or more game objects identified by id. Deletion is asynchronous meaning that
the game object(s) are scheduled for deletion which will happen at the end of the current
frame. Note that game objects scheduled for deletion will be counted against
max_instances in "game.project" until they are actually removed.
Deleting a game object containing a particle FX component emitting particles will not immediately stop the particle FX from emitting particles. You need to manually stop the particle FX using particlefx.stop().
Deleting a game object containing a sound component that is playing will not immediately stop the sound from playing. You need to manually stop the sound using sound.stop().
(id?: SceneGameObjectAddress | Hash | Url | (SceneGameObjectAddress | Hash | Url)[] | LuaPairsIterable<AnyNotNil, SceneGameObjectAddress | Hash | Url> | boolean)(id: SceneGameObjectAddress | Hash | Url | (SceneGameObjectAddress | Hash | Url)[] | LuaPairsIterable<AnyNotNil, SceneGameObjectAddress | Hash | Url>, recursive: boolean)Parameters
id:SceneGameObjectAddress | Hash | Url | (SceneGameObjectAddress | Hash | Url)[] | LuaPairsIterable<AnyNotNil, SceneGameObjectAddress | Hash | Url>— optional id or table of id's of the instance(s) to delete, the instance of the calling script is deleted by defaultrecursive:boolean— optional boolean, set to true to recursively delete child hiearchy in child to parent order
This example demonstrates how to delete game objects
// Delete the script's own game object.
go.delete();
// Delete a game object with the id "my_game_object".
const id = go.get_id("my_game_object"); // retrieve the id of the game object to be deleted
go.delete(id);
// Delete a list of game objects.
const ids = [hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3")];
go.delete(ids);-- Delete the script game object
go.delete()
-- Delete a game object with the id "my_game_object".
local id = go.get_id("my_game_object") -- retrieve the id of the game object to be deleted
go.delete(id)
-- Delete a list of game objects.
local ids = { hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3") }
go.delete(ids)This example demonstrates how to delete a game objects and their children (child to parent order)
// Delete the script's own game object and its children.
go.delete(true);
// Delete a game object with the id "my_game_object" and its children.
const id = go.get_id("my_game_object"); // retrieve the id of the game object to be deleted
go.delete(id, true);
// Delete a list of game objects and their children.
const ids = [hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3")];
go.delete(ids, true);-- Delete the script game object and it's children
go.delete(true)
-- Delete a game object with the id "my_game_object" and it's children.
local id = go.get_id("my_game_object") -- retrieve the id of the game object to be deleted
go.delete(id, true)
-- Delete a list of game objects and their children.
local ids = { hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3") }
go.delete(ids, true)go.exists(url: SceneGameObjectAddress | Hash | Url): boolean
This function can check for game objects in any collection by specifying the collection name in the URL.
Check if game object "my_game_object" exists in the current collection
go.exists("/my_game_object");go.exists("/my_game_object")Check if game object exists in another collection
go.exists("other_collection:/my_game_object");go.exists("other_collection:/my_game_object")Parameters
url:SceneGameObjectAddress | Hash | Url— url of the game object to check
Returns
exists:boolean— true if the game object exists
go.get(3 overloads)C
gets a named property of the specified game object or component
<P>(): <K extends keyof P>(url: SceneAddress | Hash | Url, property: K, ...options: [] | [GoPropertyOptions]) => P[K]<R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K): PropertyRead<AddressCatalog<R>["catalog"], K><R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K, options: GoPropertyOptions): PropertyRead<AddressCatalog<R>["catalog"], K>Parameters
url:R— url of the game object or component having the propertyproperty:K— id of the property to retrieveoptions:GoPropertyOptions— optional options table- index number index into array property (1 based)
- key hash name of internal property
- keys table array of internal component resources identified by key (e.g. a particle fx emitter, see examples below)
indexis 1-based; passed to Defold unchanged.
Returns
value:PropertyRead<AddressCatalog<R>["catalog"], K>— the value of the specified property
Get a property "speed" from a script "player", the property must be declared in the player-script:
go.property("speed", 50);go.property("speed", 50)Then in the calling script (assumed to belong to the same game object, but does not have to):
const speed = go.get("#player", "speed");local speed = go.get("#player", "speed")Get a value in a material property array
const url = msg.url("#mesh");
// get the first vector4 in the array: example[0] (the glsl indices are 0-based)
go.get(url, "example", { index: 1 });
// get the last vector4 in the array: example[15] (the glsl indices are 0-based)
go.get(url, "example", { index: 16 });
// get an element of a vector4 in the array: example[0].x (the glsl indices are 0-based)
go.get(url, "example.x", { index: 1 });-- get the first vector4 in the array: example[0] (the glsl indices are 0-based)
go.get(url, "example", {index=1})
-- get the last vector4 in the array: example[15] (the glsl indices are 0-based)
go.get(url, "example", {index=16})
-- get an element of a vector4 in the array: example[0].x (the glsl indices are 0-based)
go.get(url, "example.x", {index=1})Getting all values in a material property array as a table
const url = msg.url("#mesh");
// get all vector4's in the constant array
go.get(url, "example");
// result: [vector4, vector4, ...]
// get all elements of the vector4's from an array
go.get(url, "example.x");
// result: [number1, number2, ...]-- get all vector4's in the constant array
go.get(url, "example")
-- result: { vector4, vector4, ... }
-- get all elements of the vector4's from an array
go.get(url, "example.x")
-- result: { number1, number2, ... }Get a named property
// get the resource of a certain gui font
const font_hash = go.get("#gui", "fonts", { key: "system_font_BIG" });-- get the resource of a certain gui font
local font_hash = go.get("#gui", "fonts", {key = "system_font_BIG"})Get a property from a sub-component, using the "keys" options table
// Addressing the first level of a component:
go.get("#particlefx", "material", { keys: ["cone_emitter"] });-- Addressing the first level of a component:
go.get("#particlefx", "material", { keys = { "cone_emitter" } })Get a property into a deeper sub-hierarchy (if the component supports it).
// Note: no built-in component supports this yet, but a custom one could.
go.get("#my_component", "some_property", { keys: ["root", "child_node"] });-- Note: There is currently no component that supports this, but a custom component could.
go.get("#my_component", "some_property", { keys = { "root", "child_node" } })go.get_id(2 overloads): Hash
Returns or constructs an instance identifier. The instance id is a hash of the absolute path to the instance.
- If
pathis specified, it can either be absolute or relative to the instance of the calling script. - If
pathis not specified, the id of the game object instance the script is attached to will be returned.
()(path: string)Parameters
path:string— path of the instance for which to return the id
Returns
id:Hash— instance id
// For the instance with path /my_sub_collection/my_instance, the following calls
// are equivalent:
const id = go.get_id(); // no path, defaults to the instance containing the calling script
print(id); // => hash: [/my_sub_collection/my_instance]
const id2 = go.get_id("/my_sub_collection/my_instance"); // absolute path
print(id2); // => hash: [/my_sub_collection/my_instance]
const id3 = go.get_id("my_instance"); // relative path
print(id3); // => hash: [/my_sub_collection/my_instance]local id = go.get_id() -- no path, defaults to the instance containing the calling script
print(id) --> hash: [/my_sub_collection/my_instance]
local id = go.get_id("/my_sub_collection/my_instance") -- absolute path
print(id) --> hash: [/my_sub_collection/my_instance]
local id = go.get_id("my_instance") -- relative path
print(id) --> hash: [/my_sub_collection/my_instance]go.get_parent(id?: SceneGameObjectAddress | Hash | Url): Hash | undefined
Get the parent for a game object instance.
Get parent of the instance containing the calling script:
const parent_id = go.get_parent();local parent_id = go.get_parent()Get parent of the instance with id "x":
const parent_id = go.get_parent("x");local parent_id = go.get_parent("x")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get parent for, defaults to the instance containing the calling script
Returns
parent_id:Hash | undefined— parent instance ornil
go.get_position(id?: SceneGameObjectAddress | Hash | Url): Vector3
The position is relative the parent (if any). Use go.get_world_position to retrieve the global world position.
Get the position of the game object instance the script is attached to:
const p = go.get_position();local p = go.get_position()Get the position of another game object instance "my_gameobject":
const pos = go.get_position("my_gameobject");local pos = go.get_position("my_gameobject")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the position for, by default the instance of the calling script
Returns
position:Vector3— instance position
go.get_rotation(id?: SceneGameObjectAddress | Hash | Url): Quaternion
The rotation is relative to the parent (if any). Use go.get_world_rotation to retrieve the global world rotation.
Get the rotation of the game object instance the script is attached to:
const r = go.get_rotation();local r = go.get_rotation()Get the rotation of another game object instance with id "x":
const r = go.get_rotation("x");local r = go.get_rotation("x")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the rotation for, by default the instance of the calling script
Returns
rotation:Quaternion— instance rotation
go.get_scale(id?: SceneGameObjectAddress | Hash | Url): Vector3
The scale is relative the parent (if any). Use go.get_world_scale to retrieve the global world 3D scale factor.
Get the scale of the game object instance the script is attached to:
const s = go.get_scale();local s = go.get_scale()Get the scale of another game object instance with id "x":
const s = go.get_scale("x");local s = go.get_scale("x")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the scale for, by default the instance of the calling script
Returns
scale:Vector3— instance scale factor
go.get_scale_uniform(id?: SceneGameObjectAddress | Hash | Url): number
The uniform scale is relative the parent (if any). If the underlying scale vector is non-uniform the min element of the vector is returned as the uniform scale factor.
Get the scale of the game object instance the script is attached to:
const s = go.get_scale_uniform();local s = go.get_scale_uniform()Get the uniform scale of another game object instance with id "x":
const s = go.get_scale_uniform("x");local s = go.get_scale_uniform("x")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the uniform scale for, by default the instance of the calling script
Returns
scale:number— uniform instance scale factor
go.get_world_position(id?: SceneGameObjectAddress | Hash | Url): Vector3
The function will return the world position calculated at the end of the previous frame. To recalculate it within the current frame, use go.update_world_transform on the instance before calling this. Use go.get_position to retrieve the position relative to the parent.
Get the world position of the game object instance the script is attached to:
const p = go.get_world_position();local p = go.get_world_position()Get the world position of another game object instance with id "x":
// Relative addressing by id — no socket prefix:
const p = go.get_world_position("x");local p = go.get_world_position("x")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the world position for, by default the instance of the calling script
Returns
position:Vector3— instance world position
go.get_world_rotation(id?: SceneGameObjectAddress | Hash | Url): Quaternion
The function will return the world rotation calculated at the end of the previous frame. To recalculate it within the current frame, use go.update_world_transform on the instance before calling this. Use go.get_rotation to retrieve the rotation relative to the parent.
Get the world rotation of the game object instance the script is attached to:
const r = go.get_world_rotation();local r = go.get_world_rotation()Get the world rotation of another game object instance with id "x":
const r = go.get_world_rotation("x");local r = go.get_world_rotation("x")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the world rotation for, by default the instance of the calling script
Returns
rotation:Quaternion— instance world rotation
go.get_world_scale(id?: SceneGameObjectAddress | Hash | Url): Vector3
The function will return the world 3D scale factor calculated at the end of the previous frame. To recalculate it within the current frame, use go.update_world_transform on the instance before calling this. Use go.get_scale to retrieve the 3D scale factor relative to the parent. This vector is derived by decomposing the transformation matrix and should be used with care. For most cases it should be fine to use go.get_world_scale_uniform instead.
Get the world 3D scale of the game object instance the script is attached to:
const s = go.get_world_scale();local s = go.get_world_scale()Get the world scale of another game object instance "x":
const s = go.get_world_scale("x");local s = go.get_world_scale("x")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the world scale for, by default the instance of the calling script
Returns
scale:Vector3— instance world 3D scale factor
go.get_world_scale_uniform(id?: SceneGameObjectAddress | Hash | Url): number
The function will return the world scale factor calculated at the end of the previous frame. To recalculate it within the current frame, use go.update_world_transform on the instance before calling this. Use go.get_scale_uniform to retrieve the scale factor relative to the parent.
Get the world scale of the game object instance the script is attached to:
const s = go.get_world_scale_uniform();local s = go.get_world_scale_uniform()Get the world scale of another game object instance with id "x":
const s = go.get_world_scale_uniform("x");local s = go.get_world_scale_uniform("x")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the world scale for, by default the instance of the calling script
Returns
scale:number— instance world scale factor
go.get_world_transform(id?: SceneGameObjectAddress | Hash | Url): Matrix4
The function will return the world transform matrix calculated at the end of the previous frame. To recalculate it within the current frame, use go.update_world_transform on the instance before calling this.
Get the world transform of the game object instance the script is attached to:
const m = go.get_world_transform();local m = go.get_world_transform()Get the world transform of another game object instance with id "x":
const m = go.get_world_transform("x");local m = go.get_world_transform("x")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the world transform for, by default the instance of the calling script
Returns
transform:Matrix4— instance world transform
go.property(8 overloads)C
- 1 overload added in Defold 1.13.2
Registers a script property, which the Defold editor exposes on every game object and collection that uses the script. Defold accepts the call only at the top level of the script, outside callbacks such as init and update. A string default needs Defold 1.13.2 or later.
Warning
In the defold-typescript toolchain, don't call go.property yourself.
Declare the property in the properties field of defineScript instead —
that is the only form that types the property onto self, and the
transpiler emits the chunk-scope go.property(...) registration Defold
needs. A direct call still registers the property at runtime, but it never
reaches self's type, so reading self.<name> in a hook is a compile
error. The build reports it as a warning and names the file.
export default defineScript({
properties: { health: 100 }, // self.health: number
});Anything below written as a direct call is Defold's own Lua documentation.
Script properties on self
carries the TypeScript form and what a direct call costs you.
(name: string, value: number): ScriptProperty<number>Parameters
name:string— the id of the propertyvalue:number— default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.
(name: string, value: boolean): ScriptProperty<boolean>Parameters
name:string— the id of the propertyvalue:boolean— default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.
(name: string, value: Hash): ScriptProperty<Hash>Parameters
name:string— the id of the propertyvalue:Hash— default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.
(name: string, value: Url): ScriptProperty<Url>Parameters
name:string— the id of the propertyvalue:Url— default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.
(name: string, value: Vector3): ScriptProperty<Vector3>Parameters
name:string— the id of the propertyvalue:Vector3— default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.
(name: string, value: Vector4): ScriptProperty<Vector4>Parameters
name:string— the id of the propertyvalue:Vector4— default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.
(name: string, value: Quaternion): ScriptProperty<Quaternion>Parameters
name:string— the id of the propertyvalue:Quaternion— default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.
(name: string, value: string): ScriptProperty<string>N- Since Defold 1.13.2
Parameters
name:string— the id of the propertyvalue:string— default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.
// This example defines a property "health" in a script. The health is decreased
// whenever someone sends a "take_damage" message to the script.
// The payload of your own message id, declared once for the whole program
// (usually in a .d.ts of its own).
declare global {
interface CustomMessages {
take_damage: { damage: number };
}
}
export default defineScript({
// Never call `go.property` yourself: the transpiler emits the chunk-scope
// `go.property("health", 100)` registration from this field, and only this
// field types the property onto `self`.
properties: { health: 100 },
init(self) {
// prints 100 to the output
print(self.health);
},
on_message(self, message_id, message) {
if (isMessage(message_id, message, "take_damage")) {
self.health = self.health - message.damage;
print(`Ouch! My health is now: ${self.health}`);
}
},
});go.property("health", 100)
function init(self)
-- prints 100 to the output
print(self.health)
end
function on_message(self, message_id, message, sender)
if message_id == hash("take_damage") then
self.health = self.health - message.damage
print("Ouch! My health is now: " .. self.health)
end
endgo.set(3 overloads)C
sets a named property of the specified game object or component, or a material constant
<P>(): <K extends WritableKey<P>>(url: SceneAddress | Hash | Url, property: K, value: XyWrite<P, K>, ...options: [] | [GoPropertyOptions]) => void<R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K, value: PropertyWrite<AddressCatalog<R>["catalog"], K>): void<R extends SceneAddress | Hash | Url, K extends PropertyName<AddressCatalog<R>>>(url: R, property: K, value: PropertyWrite<AddressCatalog<R>["catalog"], K>, options: GoPropertyOptions): voidParameters
url:R— url of the game object or component having the propertyproperty:K— id of the property to setvalue:PropertyWrite<AddressCatalog<R>["catalog"], K>— the value to setoptions:GoPropertyOptions— optional options table- index integer index into array property (1 based)
- key hash name of internal property
- keys table array of internal component resources identified by key (e.g. a particle fx emitter, see examples below)
indexis 1-based; passed to Defold unchanged.
Set a property "speed" of a script "player", the property must be declared in the player-script:
go.property("speed", 50);go.property("speed", 50)Then in the calling script (assumed to belong to the same game object, but does not have to):
go.set("#player", "speed", 100);go.set("#player", "speed", 100)Set a vector4 in a material property array
const url = msg.url("#mesh");
// set the first vector4 in the array: example[0] = v (the glsl indices are 0-based)
go.set(url, "example", vmath.vector4(1, 1, 1, 1), { index: 1 });
// set the last vector4 in the array: example[15] = v (the glsl indices are 0-based)
go.set(url, "example", vmath.vector4(2, 2, 2, 2), { index: 16 });
// set an element of a vector4 in the array: example[0].x = 7 (the glsl indices are 0-based)
go.set(url, "example.x", 7, { index: 1 });-- set the first vector4 in the array: example[0] = v (the glsl indices are 0-based)
go.set(url, "example", vmath.vector4(1,1,1,1), {index=1})
-- set the last vector4 in the array: example[15] = v (the glsl indices are 0-based)
go.set(url, "example", vmath.vector4(2,2,2,2), {index=16})
-- set an element of a vector4 in the array: example[0].x = 7 (the glsl indices are 0-based)
go.set(url, "example.x", 7, {index=1})Set a material property array by a table of vector4
const url = msg.url("#mesh");
// set the first two vector4's in the array
// if the array has more than two elements in the array they will not be set
go.set(url, "example", [vmath.vector4(1, 1, 1, 1), vmath.vector4(2, 2, 2, 2)]);-- set the first two vector4's in the array
-- if the array has more than two elements in the array they will not be set
go.set(url, "example", { vmath.vector4(1,1,1,1), vmath.vector4(2,2,2,2) })Set a named property
go.property("big_font", resource.font());
function set_named_font(self: { big_font: Hash }) {
go.set("#gui", "fonts", self.big_font, { key: "system_font_BIG" });
}go.property("big_font", resource.font())
function init(self)
go.set("#gui", "fonts", self.big_font, {key = "system_font_BIG"})
endSet a property on a sub-component, using the "keys" options table
export default defineScript({
// Never call `go.property` yourself: the transpiler emits the chunk-scope
// registration from this field, and only this field types the property onto `self`.
properties: { my_material: resource.material() },
init(self) {
go.set("#particlefx", "material", self.my_material, { keys: ["cone_emitter"] });
},
});go.property("my_material", resource.material)
function init(self)
go.set("#particlefx", "material", self.my_material, { keys = { "cone_emitter" } })
endSet a property in a deeper sub-hierarchy (if the component supports it).
// Note: no built-in component supports this yet, but a custom one could.
const some_value = 1;
go.set("#my_component", "some_property", some_value, { keys: ["root", "child_node"] });-- Note: There is currently no component that supports this, but a custom component could.
go.set("#my_component", "some_property", some_value, { keys = { "root", "child_node" } })go.set_parent(id?: SceneGameObjectAddress | Hash | Url, parent_id?: SceneGameObjectAddress | Hash | Url, keep_world_transform?: boolean): void
Sets the parent for a game object instance. This means that the instance will exist in the geometrical space of its parent,
like a basic transformation hierarchy or scene graph. If no parent is specified, the instance will be detached from any parent and exist in world
space.
This function will generate a set_parent message. It is not until the message has been processed that the change actually takes effect. This
typically happens later in the same frame or the beginning of the next frame. Refer to the manual to learn how messages are processed by the
engine.
Attach myself to another instance "my_parent":
go.set_parent(go.get_id(), go.get_id("my_parent"));go.set_parent(go.get_id(),go.get_id("my_parent"))Attach an instance "my_instance" to another instance "my_parent":
go.set_parent(go.get_id("my_instance"), go.get_id("my_parent"));go.set_parent(go.get_id("my_instance"),go.get_id("my_parent"))Detach an instance "my_instance" from its parent (if any):
go.set_parent(go.get_id("my_instance"));go.set_parent(go.get_id("my_instance"))Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to set parent for, defaults to the instance containing the calling scriptparent_id?:SceneGameObjectAddress | Hash | Url— optional id of the new parent game object, defaults to detaching game object from its parentkeep_world_transform?:boolean— optional boolean, set to true to maintain the world transform when changing spaces. Defaults to false.
go.set_position(position: Vector3, id?: SceneGameObjectAddress | Hash | Url): void
The position is relative to the parent (if any). The global world position cannot be manually set.
Set the position of the game object instance the script is attached to:
// `p` is the desired position (a Vector3).
const p = vmath.vector3();
go.set_position(p);local p = ...
go.set_position(p)Set the position of another game object instance with id "x":
// `p` is the desired position (a Vector3).
const p = vmath.vector3();
// Relative addressing by id — no socket prefix:
go.set_position(p, "x");local p = ...
go.set_position(p, "x")Parameters
position:Vector3— position to setid?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to set the position for, by default the instance of the calling script
go.set_rotation(rotation: Quaternion, id?: SceneGameObjectAddress | Hash | Url): void
The rotation is relative to the parent (if any). The global world rotation cannot be manually set.
Set the rotation of the game object instance the script is attached to:
// `r` is the desired rotation (a Quaternion).
const r = vmath.quat();
go.set_rotation(r);local r = ...
go.set_rotation(r)Set the rotation of another game object instance with id "x":
// `r` is the desired rotation (a Quaternion).
const r = vmath.quat();
go.set_rotation(r, "x");local r = ...
go.set_rotation(r, "x")Parameters
rotation:Quaternion— rotation to setid?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the rotation for, by default the instance of the calling script
go.set_scale(scale: number | Vector3, id?: SceneGameObjectAddress | Hash | Url): void
The scale factor is relative to the parent (if any). The global world scale factor cannot be manually set. See manual to know how physics affected when setting scale from this function.
Set the scale of the game object instance the script is attached to:
const s = vmath.vector3(2.0, 1.0, 1.0);
go.set_scale(s);local s = vmath.vector3(2.0, 1.0, 1.0)
go.set_scale(s)Set the scale of another game object instance with id "obj_id":
const s = 1.2;
go.set_scale(s, "obj_id");local s = 1.2
go.set_scale(s, "obj_id")Parameters
scale:number | Vector3— vector or uniform scale factor, must be greater than 0id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the scale for, by default the instance of the calling script
go.set_scale_xy(scale: number | Vector3, id?: SceneGameObjectAddress | Hash | Url): void
The scale factor is relative to the parent (if any). The global world scale factor cannot be manually set. See manual to know how physics affected when setting scale from this function.
Set the scale of the game object instance the script is attached to:
const s = vmath.vector3(2.0, 1.0, 5.0);
go.set_scale_xy(s); // z will not be set here, only x and ylocal s = vmath.vector3(2.0, 1.0, 5.0)
go.set_scale_xy(s) -- z will not be set here, only x and ySet the scale of another game object instance with id "obj_id":
const s = 1.2;
go.set_scale_xy(s, "obj_id"); // z will not be set here, only x and ylocal s = 1.2
go.set_scale_xy(s, "obj_id") -- z will not be set here, only x and yParameters
scale:number | Vector3— vector or uniform scale factor, must be greater than 0id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to get the scale for, by default the instance of the calling script
go.update_world_transform(id?: SceneGameObjectAddress | Hash | Url): void
Recalculates and updates the cached world transform immediately for the target instance and its ancestors (parent chain up to the collection root). Descendants (children) are not updated by this function. If no id is provided, the instance of the calling script is used. Use this after changing local transform mid-frame when you need the new world transform right away (e.g. before end-of-frame updates). Note that child instances will still have last-frame world transforms until the regular update.
Update this game object's world transform:
go.update_world_transform();go.update_world_transform()Update another game object's world transform:
go.update_world_transform("/other");go.update_world_transform("/other")Parameters
id?:SceneGameObjectAddress | Hash | Url— optional id of the game object instance to update
go.world_to_local_position(position: Vector3, url?: SceneGameObjectAddress | Hash | Url): Vector3
The function uses world transformation calculated at the end of previous frame.
// Convert position of "test" game object into coordinate space of "child" object.
const test_pos = go.get_world_position("/test");
const child_pos = go.get_world_position("/child");
const new_position = go.world_to_local_position(test_pos, "/child"); local test_pos = go.get_world_position("/test")
local child_pos = go.get_world_position("/child")
local new_position = go.world_to_local_position(test_pos, "/child")Parameters
position:Vector3— position which need to be convertedurl?:SceneGameObjectAddress | Hash | Url— url of the game object which coordinate system convert to
Returns
converted_postion:Vector3— converted position
go.world_to_local_transform(transformation: Matrix4, url?: SceneGameObjectAddress | Hash | Url): Matrix4
The function uses world transformation calculated at the end of previous frame.
// Convert transform of "test" game object into coordinate space of "child" object.
const test_transform = go.get_world_transform("/test");
const child_transform = go.get_world_transform("/child");
const result_transform = go.world_to_local_transform(test_transform, "/child"); local test_transform = go.get_world_transform("/test")
local child_transform = go.get_world_transform("/child")
local result_transform = go.world_to_local_transform(test_transform, "/child")Parameters
transformation:Matrix4— transformation which need to be convertedurl?:SceneGameObjectAddress | Hash | Url— url of the game object which coordinate system convert to
Returns
converted_transform:Matrix4— converted transformation
Constants
go.EASING_INBACK: number & { readonly __brand: "go.EASING_INBACK" }
in-back
go.EASING_INBOUNCE: number & { readonly __brand: "go.EASING_INBOUNCE" }
in-bounce
go.EASING_INCIRC: number & { readonly __brand: "go.EASING_INCIRC" }
in-circlic
go.EASING_INCUBIC: number & { readonly __brand: "go.EASING_INCUBIC" }
in-cubic
go.EASING_INELASTIC: number & { readonly __brand: "go.EASING_INELASTIC" }
in-elastic
go.EASING_INEXPO: number & { readonly __brand: "go.EASING_INEXPO" }
in-exponential
go.EASING_INOUTBACK: number & { readonly __brand: "go.EASING_INOUTBACK" }
in-out-back
go.EASING_INOUTBOUNCE: number & { readonly __brand: "go.EASING_INOUTBOUNCE" }
in-out-bounce
go.EASING_INOUTCIRC: number & { readonly __brand: "go.EASING_INOUTCIRC" }
in-out-circlic
go.EASING_INOUTCUBIC: number & { readonly __brand: "go.EASING_INOUTCUBIC" }
in-out-cubic
go.EASING_INOUTELASTIC: number & { readonly __brand: "go.EASING_INOUTELASTIC" }
in-out-elastic
go.EASING_INOUTEXPO: number & { readonly __brand: "go.EASING_INOUTEXPO" }
in-out-exponential
go.EASING_INOUTQUAD: number & { readonly __brand: "go.EASING_INOUTQUAD" }
in-out-quadratic
go.EASING_INOUTQUART: number & { readonly __brand: "go.EASING_INOUTQUART" }
in-out-quartic
go.EASING_INOUTQUINT: number & { readonly __brand: "go.EASING_INOUTQUINT" }
in-out-quintic
go.EASING_INOUTSINE: number & { readonly __brand: "go.EASING_INOUTSINE" }
in-out-sine
go.EASING_INQUAD: number & { readonly __brand: "go.EASING_INQUAD" }
in-quadratic
go.EASING_INQUART: number & { readonly __brand: "go.EASING_INQUART" }
in-quartic
go.EASING_INQUINT: number & { readonly __brand: "go.EASING_INQUINT" }
in-quintic
go.EASING_INSINE: number & { readonly __brand: "go.EASING_INSINE" }
in-sine
go.EASING_LINEAR: number & { readonly __brand: "go.EASING_LINEAR" }
linear interpolation
go.EASING_OUTBACK: number & { readonly __brand: "go.EASING_OUTBACK" }
out-back
go.EASING_OUTBOUNCE: number & { readonly __brand: "go.EASING_OUTBOUNCE" }
out-bounce
go.EASING_OUTCIRC: number & { readonly __brand: "go.EASING_OUTCIRC" }
out-circlic
go.EASING_OUTCUBIC: number & { readonly __brand: "go.EASING_OUTCUBIC" }
out-cubic
go.EASING_OUTELASTIC: number & { readonly __brand: "go.EASING_OUTELASTIC" }
out-elastic
go.EASING_OUTEXPO: number & { readonly __brand: "go.EASING_OUTEXPO" }
out-exponential
go.EASING_OUTINBACK: number & { readonly __brand: "go.EASING_OUTINBACK" }
out-in-back
go.EASING_OUTINBOUNCE: number & { readonly __brand: "go.EASING_OUTINBOUNCE" }
out-in-bounce
go.EASING_OUTINCIRC: number & { readonly __brand: "go.EASING_OUTINCIRC" }
out-in-circlic
go.EASING_OUTINCUBIC: number & { readonly __brand: "go.EASING_OUTINCUBIC" }
out-in-cubic
go.EASING_OUTINELASTIC: number & { readonly __brand: "go.EASING_OUTINELASTIC" }
out-in-elastic
go.EASING_OUTINEXPO: number & { readonly __brand: "go.EASING_OUTINEXPO" }
out-in-exponential
go.EASING_OUTINQUAD: number & { readonly __brand: "go.EASING_OUTINQUAD" }
out-in-quadratic
go.EASING_OUTINQUART: number & { readonly __brand: "go.EASING_OUTINQUART" }
out-in-quartic
go.EASING_OUTINQUINT: number & { readonly __brand: "go.EASING_OUTINQUINT" }
out-in-quintic
go.EASING_OUTINSINE: number & { readonly __brand: "go.EASING_OUTINSINE" }
out-in-sine
go.EASING_OUTQUAD: number & { readonly __brand: "go.EASING_OUTQUAD" }
out-quadratic
go.EASING_OUTQUART: number & { readonly __brand: "go.EASING_OUTQUART" }
out-quartic
go.EASING_OUTQUINT: number & { readonly __brand: "go.EASING_OUTQUINT" }
out-quintic
go.EASING_OUTSINE: number & { readonly __brand: "go.EASING_OUTSINE" }
out-sine
go.PLAYBACK_LOOP_BACKWARD: number & { readonly __brand: "go.PLAYBACK_LOOP_BACKWARD" }
loop backward
go.PLAYBACK_LOOP_FORWARD: number & { readonly __brand: "go.PLAYBACK_LOOP_FORWARD" }
loop forward
go.PLAYBACK_LOOP_PINGPONG: number & { readonly __brand: "go.PLAYBACK_LOOP_PINGPONG" }
ping pong loop
go.PLAYBACK_NONE: number & { readonly __brand: "go.PLAYBACK_NONE" }
no playback
go.PLAYBACK_ONCE_BACKWARD: number & { readonly __brand: "go.PLAYBACK_ONCE_BACKWARD" }
once backward
go.PLAYBACK_ONCE_FORWARD: number & { readonly __brand: "go.PLAYBACK_ONCE_FORWARD" }
once forward
go.PLAYBACK_ONCE_PINGPONG: number & { readonly __brand: "go.PLAYBACK_ONCE_PINGPONG" }
once ping pong
Properties
euler: Vector3
The rotation of the game object expressed in Euler angles. Euler angles are specified in degrees in the interval (-360, 360). The type of the property is vector3.
position: Vector3
The position of the game object. The type of the property is vector3.
rotation: Quaternion
The rotation of the game object. The type of the property is quaternion.
scale: number | Vector3
The scale of the game object. go.get returns a vector3; go.set and go.animate also take a number, which sets a uniform scale.