scene
A scene stack the loop dispatches to, for menus, levels and pause screens.
A game is usually several screens, a title menu, the play field, a pause
overlay, a game-over screen, each with its own update, draw and input. Wiring
all of that into one set of callbacks behind a mode flag gets tangled. The
scene module keeps each screen as its own Scene, and a SceneManager
decides which one is live. You override the parts of a scene you care about,
and the manager calls them at the right time.
A scene is a ref object of Scene with methods you override. enter and
leave are the setup and teardown hooks, update and draw run each frame,
and the input methods (keydown, mousepressed and the rest) mirror the
engine callbacks. Every method has a do-nothing default, so you write only the
ones a scene actually needs, and the scene's own fields hold its state.
The manager holds a stack. switch replaces the top scene, push lays a new
one over it, and pop drops back to the one beneath, which is how a pause
screen sits on top of the still-visible game. The top scene gets update and
input, while draw runs over the whole stack from the bottom up, so an overlay
that does not clear shows what is under it. newSceneManager takes over the
engine's update, draw and input callbacks, so once it is wired the live scene
receives everything on its own.
This is an opt-in module, imported on its own with import nim2d/scene. The
core engine does not pull it in.
type Scene = ref object
The base every scene inherits from. Make your own with
type TitleScene = ref object of Scene, give it whatever fields it needs to
hold its state, and override the methods below for the behavior you want.
type SceneManager = ref object
Holds the scene stack and routes the engine's
callbacks to it. Make one with newSceneManager.
push ¶
proc push(mgr: SceneManager; scene: Scene)
Lay scene on top of the stack and call its enter. The scene below stays
in place and keeps drawing under it, which is how an overlay like a pause screen works.
Parameters
-
mgr(SceneManager) -
scene(Scene)
pop ¶
proc pop(mgr: SceneManager)
Drop the top scene, calling its leave, so the one beneath becomes live
again. Does nothing on an empty stack.
Parameters
-
mgr(SceneManager)
switch ¶
proc switch(mgr: SceneManager; scene: Scene)
Replace the top scene with scene, calling leave on the old top and
enter on the new one. Anything deeper in the stack is left alone. On an
empty stack this is the same as push.
Parameters
-
mgr(SceneManager) -
scene(Scene)
clear ¶
proc clear(mgr: SceneManager)
Drop every scene, calling leave on each from the top down, leaving the
stack empty.
Parameters
-
mgr(SceneManager)
current ¶
proc current(mgr: SceneManager): Scene
The live scene, the one on top of the stack, or nil when the stack is
empty.
Parameters
-
mgr(SceneManager)
Returns
Scene
count ¶
proc count(mgr: SceneManager): int
How many scenes are on the stack.
Parameters
-
mgr(SceneManager)
Returns
int
newSceneManager ¶
proc newSceneManager(nim2d: Nim2d; initial: Scene = nil): SceneManager
Make a scene manager and point the engine's update, draw and input
callbacks at it, so from here on the live scene receives them. Pass an
initial scene to start with, or leave it out and push one yourself. An
initial scene's enter runs during this call, before the manager is
returned, so if that scene's enter needs to reach the manager, leave
initial out and push it once the manager is assigned.
Parameters
-
nim2d(Nim2d) -
initial(Scene)
Returns
SceneManager