factory
Functions for controlling factory components which are used to dynamically spawn game objects into the runtime.
Functions
factory.create(url: string | Hash | Url, position?: Vector3, rotation?: Quaternion, properties?: LuaPairsIterable<string, number | boolean | string | Hash | Url | Vector3 | Vector4 | Quaternion> | (PlainTable & { readonly __tstlIterable?: never }), scale?: number | Vector3): Hash | undefinedfactory.get_status(url: string | Hash | Url):factory.Statusfactory.load(url: string | Hash | Url, complete_function: (self: unknown, url: unknown, result: unknown) => void): voidfactory.set_prototype(url: string | Hash | Url, prototype: string | undefined): voidfactory.unload(url: string | Hash | Url): void
factory.create(url: string | Hash | Url, position?: Vector3, rotation?: Quaternion, properties?: LuaPairsIterable<string, number | boolean | string | Hash | Url | Vector3 | Vector4 | Quaternion> | (PlainTable & { readonly __tstlIterable?: never }), scale?: number | Vector3): Hash | undefined
The URL identifies which factory should create the game object. If the game object is created inside of the frame (e.g. from an update callback), the game object will be created instantly, but none of its component will be updated in the same frame. Properties defined in scripts in the created game object can be overridden through the properties-parameter below. See go.property for more information on script properties. Calling factory.create on a factory that is marked as dynamic without having loaded resources using factory.load will synchronously load and create resources which may affect application performance.
How to create a new game object:
export default defineScript({
init(self) {
// create a new game object and provide property values
const created = factory.create("#factory", undefined, undefined, { my_value: 1 });
// communicate with the object
if (created !== undefined) {
msg.post(created, "hello");
}
},
});function init(self)
-- create a new game object and provide property values
self.my_created_object = factory.create("#factory", nil, nil, {my_value = 1})
-- communicate with the object
msg.post(self.my_created_object, "hello")
endAnd then let the new game object have a script attached:
go.property("my_value", 0);
export default defineScript({
init(self) {
// do something with self.my_value which is now one
},
});go.property("my_value", 0)
function init(self)
-- do something with self.my_value which is now one
endParameters
url:string | Hash | Url— the factory that should create a game object.position?:Vector3— the position of the new game object, the position of the game object callingfactory.create()is used by default, or if the value isnil.rotation?:Quaternion— the rotation of the new game object, the rotation of the game object callingfactory.create()is used by default, or if the value isnil.properties?:LuaPairsIterable<string, number | boolean | string | Hash | Url | Vector3 | Vector4 | Quaternion> | (PlainTable & { readonly __tstlIterable?: never })— the properties defined in a script attached to the new game object.scale?:number | Vector3— the scale of the new game object (must be greater than 0), the scale of the game object containing the factory is used by default, or if the value isnil
Returns
id:Hash | undefined— the global id of the spawned game object
factory.get_status(url: string | Hash | Url): factory.Status
This returns status of the factory. Calling this function when the factory is not marked as dynamic loading always returns factory.STATUS_LOADED.
Parameters
url:string | Hash | Url— the factory component to get status from
Returns
status:factory.Status— status of the factory component
factory.load(url: string | Hash | Url, complete_function: (self: unknown, url: unknown, result: unknown) => void): void
Resources are referenced by the factory component until the existing (parent) collection is destroyed or factory.unload is called. Calling this function when the factory is not marked as dynamic loading does nothing.
// How to load resources of a factory prototype.
factory.load("#factory", (self, url, result) => {});factory.load("#factory", function(self, url, result) end)Parameters
url:string | Hash | Url— the factory component to loadcomplete_function:(self: unknown, url: unknown, result: unknown) => void— function to call when resources are loaded.selfscript_instance The current script instance.urlurl url of the factory componentresultboolean True if resources were loaded successfully
factory.set_prototype(url: string | Hash | Url, prototype: string | undefined): void
Changes the prototype for the factory.
// How to unload the previous prototype's resources, and then spawn a new game object:
factory.unload("#factory"); // unload the previous resources
factory.set_prototype("#factory", "/main/levels/enemyA.goc");
const id = factory.create("#factory", go.get_world_position(), vmath.quat());factory.unload("#factory") -- unload the previous resources
factory.set_prototype("#factory", "/main/levels/enemyA.goc")
local id = factory.create("#factory", go.get_world_position(), vmath.quat())Parameters
url:string | Hash | Url— the factory componentprototype:string | undefined— the path to the new prototype, ornil
factory.unload(url: string | Hash | Url): void
This decreases the reference count for each resource loaded with factory.load. If reference is zero, the resource is destroyed. Calling this function when the factory is not marked as dynamic loading does nothing.
// How to unload resources of a factory prototype loaded with factory.load:
factory.unload("#factory");factory.unload("#factory")Parameters
url:string | Hash | Url— the factory component to unload
Constants
factory.STATUS_LOADED: number & { readonly __brand: "factory.STATUS_LOADED" }
The factory resources are loaded.
factory.STATUS_LOADING: number & { readonly __brand: "factory.STATUS_LOADING" }
The factory resources are loading.
factory.STATUS_UNLOADED: number & { readonly __brand: "factory.STATUS_UNLOADED" }
The factory resources are unloaded.