Skip to Content
defold-typescript libraries
baochungitdefold-wrap

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
    1. Pick a release from baochungit/defold-wrap releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as gui_scene from "wrap.gui_scene"

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 name open_modal takes.
  • object_class: C — A class wrap.gui_object.extend returns.
  • props?: Partial<C['props']> — Props open_modal starts from, before its own are copied over them.
  • settings?: Partial<C['settings']> — Settings open_modal starts 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 name open_modal takes.
  • object_class: GuiObjectHooks<F> — The hooks and fields, each hook seeing the object as this.
  • props?: object — Props open_modal starts from, before its own are copied over them.
  • settings?: object — Settings open_modal starts 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, or nil when 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 class wrap.gui_object.extend returns, 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 class wrap.gui_object.extend returns, 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 class wrap.gui_object.extend returns.
  • props: C['props'] | Defaulted<C['props']> — The object's props, or undefined for {} 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 root root is 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, or nil for mouse movement.
  • action: go.on_input.Action — The input data.

Returns

  • boolean — true to consume the input. The no-op returns false.

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, or nil for mouse movement.
  • action: go.on_input.Action — The input data.

Returns

  • boolean — Whether an object or on_input consumed 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 to 0.5.
  • wait?: number — The delay in seconds before it starts. Defaults to 0.
  • easing?: gui.Easing | Vector — The easing. Defaults to gui.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 to 0.5.
  • wait?: number — The delay in seconds before it starts. Defaults to 0.
  • easing?: gui.Easing | Vector — The easing. Defaults to gui.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 to 0.5.
  • wait?: number — The delay in seconds before it starts. Defaults to 0.
  • easing?: gui.Easing | Vector — The easing. Defaults to gui.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 to 0.5.
  • wait?: number — The delay in seconds before it starts. Defaults to 0.
  • easing?: gui.Easing | Vector — The easing. Defaults to gui.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 to 0.5.
  • wait?: number — The delay in seconds before it starts. Defaults to 0.
  • easing?: gui.Easing | Vector — The easing. Defaults to gui.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 to 0.5.
  • wait?: number — The delay in seconds before it starts. Defaults to 0.
  • easing?: gui.Easing | Vector — The easing. Defaults to gui.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 to 0.5.
  • wait?: number — The delay in seconds before it starts. Defaults to 0.
  • easing?: gui.Easing | Vector — The easing. Defaults to gui.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 to 0.5.
  • wait?: number — The delay in seconds before it starts. Defaults to 0.
  • easing?: gui.Easing | Vector — The easing. Defaults to gui.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 to 0.5.
  • wait?: number — The delay in seconds before it starts. Defaults to 0.
  • easing?: gui.Easing | Vector — The easing. Defaults to gui.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 to 0.5.
  • wait?: number — The delay in seconds before it starts. Defaults to 0.
  • easing?: gui.Easing | Vector — The easing. Defaults to gui.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.

On this page

Functionsnew(): GuiSceneextend<F extends object = {}>(): GuiSceneClass<F>Variables__name: 'GuiScene'Typestype Transition = (this: void, on_done: (this: void) => void) => voidtype GuiSceneClass<F extends object = {}> = GuiScene & F & { 'new'(this: void): GuiScene & F; }GuiSceneGuiScene.register_modal<C extends AnyGuiObjectClass>(name: string, object_class: C, props?: Partial<C['props']>, settings?: Partial<C['settings']>)GuiScene.register_modal<F extends object = {}>(name: string, object_class: GuiObjectHooks<F>, props?: object, settings?: object)GuiScene.unregister_modal(name: string)GuiScene.open_modal(name: string, props?: object, settings?: object): GuiObject | undefinedGuiScene.new_object<C extends AnyGuiObjectClass>(object_class: C & Omittable<C['props']> & Omittable<C['settings']>, props?: C['props'], settings?: C['settings']): ReturnType<C['new']>GuiScene.new_object<C extends AnyGuiObjectClass>(object_class: C & Omittable<C['settings']>, props: C['props'], settings?: C['settings']): ReturnType<C['new']>GuiScene.new_object<C extends AnyGuiObjectClass>(object_class: C, props: C['props'] | Defaulted<C['props']>, settings: C['settings']): ReturnType<C['new']>GuiScene.setup(app: GuiApplet)GuiScene.is_alive(): boolean | undefinedGuiScene.is_ready(): booleanGuiScene.set_transitions(transitions?: Transitions)GuiScene.transition_in(callback?: () => void)GuiScene.set_transition_in_done()GuiScene.transition_out(callback?: () => void)GuiScene.set_transition_out_done()GuiScene.on_ready()GuiScene.init()GuiScene.update(dt: number)GuiScene.final()GuiScene.on_message(message_id: Hash, message: Record<string | number, unknown>, sender: Url)GuiScene.on_input(action_id: Hash | undefined, action: go.on_input.Action): booleanGuiScene.bg_update(dt: number)GuiScene.bg_final()GuiScene.bg_on_message(message_id: Hash, message: Record<string | number, unknown>, sender: Url)GuiScene.bg_on_input(action_id: Hash | undefined, action: go.on_input.Action): booleanGuiScene.fade_in(time?: number, wait?: number, easing?: gui.Easing | Vector): TransitionGuiScene.fade_out(time?: number, wait?: number, easing?: gui.Easing | Vector): TransitionGuiScene.slide_in_top(time?: number, wait?: number, easing?: gui.Easing | Vector): TransitionGuiScene.slide_in_bottom(time?: number, wait?: number, easing?: gui.Easing | Vector): TransitionGuiScene.slide_in_right(time?: number, wait?: number, easing?: gui.Easing | Vector): TransitionGuiScene.slide_in_left(time?: number, wait?: number, easing?: gui.Easing | Vector): TransitionGuiScene.slide_out_top(time?: number, wait?: number, easing?: gui.Easing | Vector): TransitionGuiScene.slide_out_bottom(time?: number, wait?: number, easing?: gui.Easing | Vector): TransitionGuiScene.slide_out_right(time?: number, wait?: number, easing?: gui.Easing | Vector): TransitionGuiScene.slide_out_left(time?: number, wait?: number, easing?: gui.Easing | Vector): TransitionGuiScene.app: GuiAppletGuiScene.root: NodeTransitionsTransitions.transition_in?: TransitionTransitions.transition_out?: Transition