baochungit/defold-wrap/wrap.gui_scene
The base class of a GUI scene: one screen of an applet, with its own hidden root box
node, the GUI objects created in it, the modals registered on it, and the transitions it
plays when it is shown and replaced. A game subclasses it with extend, assigns hooks
to the subclass, and hands it to an applet's register_scene or show_scene.
- GitHub: baochungit/defold-wrap — pinned to
1.1.0- Pick a release from baochungit/defold-wrap releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as gui_scene from "wrap.gui_scene"
- Pick a release from baochungit/defold-wrap releases and add its Source code (zip) URL (or a packaged
Functions
new(): GuiScene
Returns a new, not yet set up scene of the base class.
Returns
GuiScene
extend<F extends object = {}>(): GuiSceneClass<F>
Returns a new subclass: a table indexing the base class, with its own new. Assign
hooks such as init and on_ready to it, and pass it to an applet. F types the
fields and methods a game adds to it.
Returns
GuiSceneClass<F>
Variables
__name: 'GuiScene'
The class name, the value register_scene and show_scene read to tell a class from
a plain table.
Types
type Transition = (this: void, on_done: (this: void) => void) => void
type GuiSceneClass<F extends object = {}> = GuiScene & F & { 'new'(this: void): GuiScene & F; }
GuiScene
GuiScene.register_modal<C extends AnyGuiObjectClass>(name: string, object_class: C, props?: Partial<C['props']>, settings?: Partial<C['settings']>)
Registers a modal under a name, for open_modal to create.
Parameters
name:string— The nameopen_modaltakes.object_class:C— A classwrap.gui_object.extendreturns.props?:Partial<C['props']>— Propsopen_modalstarts from, before its own are copied over them.settings?:Partial<C['settings']>— Settingsopen_modalstarts from, before its own are copied over them.
GuiScene.register_modal<F extends object = {}>(name: string, object_class: GuiObjectHooks<F>, props?: object, settings?: object)
Registers a modal built from a plain table of hooks and fields, whose keys are copied
onto a fresh wrap.gui_object.extend() once, at registration.
Parameters
name:string— The nameopen_modaltakes.object_class:GuiObjectHooks<F>— The hooks and fields, each hook seeing the object asthis.props?:object— Propsopen_modalstarts from, before its own are copied over them.settings?:object— Settingsopen_modalstarts from, before its own are copied over them.
GuiScene.unregister_modal(name: string)
Removes the modal registered under a name.
Parameters
name:string— The name it was registered under.
GuiScene.open_modal(name: string, props?: object, settings?: object): GuiObject | undefined
Creates the modal registered under a name with new_object. Its props are a copy of
the registered props with the given ones copied over them, and its settings the same.
Parameters
name:string— The name it was registered under.props?:object— Props copied over the registered ones.settings?:object— Settings copied over the registered ones.
Returns
GuiObject | undefined— The modal, ornilwhen no modal is registered under the name.
GuiScene.new_object<C extends AnyGuiObjectClass>(object_class: C & Omittable<C['props']> & Omittable<C['settings']>, props?: C['props'], settings?: C['settings']): ReturnType<C['new']>
Creates an object in the scene: calls the class's new, sets the instance up with
setup, which runs its init, and adds it to the objects bg_update, bg_final
and bg_on_input fan out to.
Parameters
object_class:C & Omittable<C['props']> & Omittable<C['settings']>— A classwrap.gui_object.extendreturns, whose props and settings may both be omitted.props?:C['props']— The object's props. Defaults to{}.settings?:C['settings']— The object's settings. Defaults to{}.
Returns
ReturnType<C['new']>
GuiScene.new_object<C extends AnyGuiObjectClass>(object_class: C & Omittable<C['settings']>, props: C['props'], settings?: C['settings']): ReturnType<C['new']>
Creates an object whose class needs props, as the first form does.
Parameters
object_class:C & Omittable<C['settings']>— A classwrap.gui_object.extendreturns, whose settings may be omitted.props:C['props']— The object's props.settings?:C['settings']— The object's settings. Defaults to{}.
Returns
ReturnType<C['new']>
GuiScene.new_object<C extends AnyGuiObjectClass>(object_class: C, props: C['props'] | Defaulted<C['props']>, settings: C['settings']): ReturnType<C['new']>
Creates an object whose class needs settings, as the first form does.
Parameters
object_class:C— A classwrap.gui_object.extendreturns.props:C['props'] | Defaulted<C['props']>— The object's props, orundefinedfor{}when the class allows it.settings:C['settings']— The object's settings.
Returns
ReturnType<C['new']>
GuiScene.setup(app: GuiApplet)
Sets the scene up in an applet and runs init. show_scene calls it on each scene
it shows; a game does not.
Parameters
app:GuiApplet— The applet showing the scene, under whose rootrootis created.
GuiScene.is_alive(): boolean | undefined
Returns whether the scene is set up and not finalized: nil until setup has run
init, so also during init, then true until bg_final makes it false.
Returns
boolean | undefined
GuiScene.is_ready(): boolean
Returns whether the scene's transition in has finished and it is not yet transitioning out, the only state in which it receives messages and input.
Returns
boolean
GuiScene.set_transitions(transitions?: Transitions)
Sets the transitions the scene plays, replacing any set before.
Parameters
transitions?:Transitions— The transitions. When omitted, the scene plays none.
GuiScene.transition_in(callback?: () => void)
Plays the transition in, if one is set, then makes the scene ready and runs
on_ready. Does nothing unless the scene is newly set up. show_scene calls it.
Parameters
callback?:() => void— Called once the scene is ready.
GuiScene.set_transition_in_done()
Resumes the transition in where it waits for its animation. The transition in calls it when done; at this tag it resumes whatever state the scene is in.
GuiScene.transition_out(callback?: () => void)
Plays the transition out, if one is set, then finalizes the scene with bg_final.
Does nothing unless the scene is ready. show_scene calls it on the scene it
replaces.
Parameters
callback?:() => void— Called once the scene is finalized.
GuiScene.set_transition_out_done()
Resumes the transition out where it waits for its animation. The transition out calls it when done; at this tag it resumes whatever state the scene is in.
GuiScene.on_ready()
Runs once the transition in has finished, from transition_in. A no-op to replace.
GuiScene.init()
Runs once setup has created root, from show_scene. A no-op to replace.
GuiScene.update(dt: number)
Runs each frame from bg_update while the scene is alive. A no-op to replace.
Parameters
dt:number— The time since the last frame, in seconds.
GuiScene.final()
Runs once from bg_final, before the objects and root are deleted. A no-op to replace.
GuiScene.on_message(message_id: Hash, message: Record<string | number, unknown>, sender: Url)
Runs from bg_on_message while the scene is ready. A no-op to replace.
Parameters
message_id:Hash— The message's id.message:Record<string | number, unknown>— The message's data.sender:Url— The url of the message's sender.
GuiScene.on_input(action_id: Hash | undefined, action: go.on_input.Action): boolean
Runs from bg_on_input when no object consumed the input. A no-op to replace.
Parameters
action_id:Hash | undefined— The input action's id, ornilfor mouse movement.action:go.on_input.Action— The input data.
Returns
boolean—trueto consume the input. The no-op returnsfalse.
GuiScene.bg_update(dt: number)
Runs update, then each object's bg_update, unless the scene is not alive. The
applet's update calls it each frame, for the scene transitioning out too.
Parameters
dt:number— The time since the last frame, in seconds.
GuiScene.bg_final()
Finalizes the scene, unless it is not alive: marks it finalized, runs final,
deletes each object, then deletes root and the nodes under it. The transition out
and the applet's final call it.
GuiScene.bg_on_message(message_id: Hash, message: Record<string | number, unknown>, sender: Url)
Passes a message to on_message while the scene is ready. The applet's on_message
calls it.
Parameters
message_id:Hash— The message's id.message:Record<string | number, unknown>— The message's data.sender:Url— The url of the message's sender.
GuiScene.bg_on_input(action_id: Hash | undefined, action: go.on_input.Action): boolean
Offers input to each object's bg_on_input, the newest first, then to on_input if
none consumed it. Returns false unless the scene is ready. The applet's on_input
calls it.
Parameters
action_id:Hash | undefined— The input action's id, ornilfor mouse movement.action:go.on_input.Action— The input data.
Returns
boolean— Whether an object oron_inputconsumed the input.
GuiScene.fade_in(time?: number, wait?: number, easing?: gui.Easing | Vector): Transition
Returns a transition that sets the root's alpha to 0 and animates it to 1.
Parameters
time?:number— The duration in seconds. Defaults to0.5.wait?:number— The delay in seconds before it starts. Defaults to0.easing?:gui.Easing | Vector— The easing. Defaults togui.EASING_LINEAR.
Returns
Transition
GuiScene.fade_out(time?: number, wait?: number, easing?: gui.Easing | Vector): Transition
Returns a transition that animates the root's alpha to 0.
Parameters
time?:number— The duration in seconds. Defaults to0.5.wait?:number— The delay in seconds before it starts. Defaults to0.easing?:gui.Easing | Vector— The easing. Defaults togui.EASING_LINEAR.
Returns
Transition
GuiScene.slide_in_top(time?: number, wait?: number, easing?: gui.Easing | Vector): Transition
Returns a transition that moves the root up by the applet's height and animates it
down to 0.
Parameters
time?:number— The duration in seconds. Defaults to0.5.wait?:number— The delay in seconds before it starts. Defaults to0.easing?:gui.Easing | Vector— The easing. Defaults togui.EASING_LINEAR.
Returns
Transition
GuiScene.slide_in_bottom(time?: number, wait?: number, easing?: gui.Easing | Vector): Transition
Returns a transition that moves the root down by the applet's height and animates it
up to 0.
Parameters
time?:number— The duration in seconds. Defaults to0.5.wait?:number— The delay in seconds before it starts. Defaults to0.easing?:gui.Easing | Vector— The easing. Defaults togui.EASING_LINEAR.
Returns
Transition
GuiScene.slide_in_right(time?: number, wait?: number, easing?: gui.Easing | Vector): Transition
Returns a transition that moves the root right by the applet's width and animates it
left to 0.
Parameters
time?:number— The duration in seconds. Defaults to0.5.wait?:number— The delay in seconds before it starts. Defaults to0.easing?:gui.Easing | Vector— The easing. Defaults togui.EASING_LINEAR.
Returns
Transition
GuiScene.slide_in_left(time?: number, wait?: number, easing?: gui.Easing | Vector): Transition
Returns a transition that moves the root left by the applet's width and animates it
right to 0.
Parameters
time?:number— The duration in seconds. Defaults to0.5.wait?:number— The delay in seconds before it starts. Defaults to0.easing?:gui.Easing | Vector— The easing. Defaults togui.EASING_LINEAR.
Returns
Transition
GuiScene.slide_out_top(time?: number, wait?: number, easing?: gui.Easing | Vector): Transition
Returns a transition that animates the root up by the applet's height.
Parameters
time?:number— The duration in seconds. Defaults to0.5.wait?:number— The delay in seconds before it starts. Defaults to0.easing?:gui.Easing | Vector— The easing. Defaults togui.EASING_LINEAR.
Returns
Transition
GuiScene.slide_out_bottom(time?: number, wait?: number, easing?: gui.Easing | Vector): Transition
Returns a transition that animates the root down by the applet's height.
Parameters
time?:number— The duration in seconds. Defaults to0.5.wait?:number— The delay in seconds before it starts. Defaults to0.easing?:gui.Easing | Vector— The easing. Defaults togui.EASING_LINEAR.
Returns
Transition
GuiScene.slide_out_right(time?: number, wait?: number, easing?: gui.Easing | Vector): Transition
Returns a transition that animates the root right by the applet's width.
Parameters
time?:number— The duration in seconds. Defaults to0.5.wait?:number— The delay in seconds before it starts. Defaults to0.easing?:gui.Easing | Vector— The easing. Defaults togui.EASING_LINEAR.
Returns
Transition
GuiScene.slide_out_left(time?: number, wait?: number, easing?: gui.Easing | Vector): Transition
Returns a transition that animates the root left by the applet's width.
Parameters
time?:number— The duration in seconds. Defaults to0.5.wait?:number— The delay in seconds before it starts. Defaults to0.easing?:gui.Easing | Vector— The easing. Defaults togui.EASING_LINEAR.
Returns
Transition
GuiScene.app: GuiApplet
The applet showing the scene, set by setup.
GuiScene.root: Node
The scene's root, a box node setup creates hidden under the applet's root. Every
object created in the scene has its own root under it, and the built-in transitions
animate it.
Transitions
Transitions.transition_in?: Transition
Played by transition_in before the scene is ready.
Transitions.transition_out?: Transition
Played by transition_out before the scene is finalized.