README
¶
gscene
A lightweight scene package for Ebitengine.
It's in active development phase, so while you can take a look, I can't recommend it yet.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Controller ¶
type Controller interface {
// Init is called once when a new scene is being created.
Init(ctx InitContext)
// Update is called at every game's Update cycle.
// The conчtroller's Update is called before any of the scene objects Update.
Update(delta float64)
}
Controller is a scene-attached object that initializes and runs a single scene. It's up to the controller to create all necessary objects and add them to the scene.
There is always only one active controller for the scene.
The Controller interface is very similar to Object interface, but it's never Disposed as the controller's lifetime is equal to the current scene's lifetime. Also, instead of just a Scene, it gets some extra data for its initialization.
type Drawer ¶
type Drawer interface {
// AddGraphics is like [Scene.AddObject], but for [Graphics].
//
// The provided layer index specifies which layer should handle
// this graphic rendering.
// Normally, layers start from 0 go up.
// Higher layers are drawned on top of lower ones.
//
// A layer can do some graphics ordering inside itself as well.
// For example, a Y-sort style layer would draw its elements
// after sorting them by Y-axis.
AddGraphics(g Graphics, layer int)
// Update is a [Drawer] hook into [ebiten.Game] Update tree.
// The [Manager.Update] will call the current Drawer's Update method.
//
// The drawer is not expected to do anything during this method,
// but it might be a good place to filter-out disposed graphical objects.
// Doing so inside the update tree might be better to waste less
// CPU cycles for irrelevant task inside the draw tree.
Update(delta float64)
// Draw is a [Drawer] hook into [ebiten.Game] Draw tree.
// The [Manager.Draw] will call the current Drawer's Draw method.
//
// The drawer is expected to draw all its layers to the [dst] image.
Draw(dst *ebiten.Image)
}
Drawer implements a drawable objects container.
Scene itself holds update tree objects like Object, but graphics (draw tree) are more complicated. There are layers, cameras, and other stuff that needs to be handled properly. This is why drawing can be configured via the interface.
There is a default implementation available plus some more in third-party libraries like ebitengine-graphics.
type Graphics ¶
type Graphics = interface {
// Draw implements the rendering method of this graphics object.
Draw(dst *ebiten.Image)
// IsDisposed reports whether graphics object was disposed.
//
// Disposed graphics are removed from the scene before their
// Draw method is called for the current frame.
IsDisposed() bool
}
Graphics is a scene-managed graphical object those Draw method will be called as a part of a game loop.
You rarely need to write your own Graphics implementation. You can find the most popular implementations like Sprite in ebitengine-graphics package.
Defined as a type alias to an anonymous interface to allow implementations that do now directly name this type. This is used in ebitengine-graphics package, for example.
type InitContext ¶
type InitContext struct {
Scene *Scene
}
InitContext is an argument type for [Controller.Init]. Most notably, the Scene is directly available through its field.
func (*InitContext) SetDrawer ¶
func (ctx *InitContext) SetDrawer(d Drawer)
SetDrawer changes the scene Drawer implementation.
The default Drawer is a single-layer implementation that ignores layer index argument of AddGraphics and renders all objects in the order they were added.
See Drawer docs to learn more about how to implement a custom drawer.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager wraps the current scene and implements scene changing logic.
It also provides the access to Update/Draw methods that should be used from the top-level game runner of ebiten.Game.
Most games only need one scene Manager. Put it somewhere in your game's context.
func NewManager ¶
func NewManager() *Manager
func (*Manager) ChangeScene ¶
func (m *Manager) ChangeScene(c Controller)
ChangeScene changes the current scene to a new one. The new scene will have the specified controller attached to it.
If there is another scene running during the time [ChangeScene] is called, its execution will be stopped. This means that ChangeScene should be treated as a control transfer call, it will not return and continue from the point it was called. After the scene is changed, no logic that is part of the Update tree from the old scene will be executed.
The [Controller.Init] method of [c] will be called after this new scene is installed.
func (*Manager) CurrentScene ¶
func (*Manager) Draw ¶
func (m *Manager) Draw(dst *ebiten.Image)
Draw calls the Draw methods on the entire scene tree.
It calls the Draw methods on scene graphics that are not disposed. The Draw call order is identical to the AddGraphics order that was used before.
Disposed graphics are removed from the objects list.
func (*Manager) IsDisposed ¶
func (*Manager) Update ¶
func (m *Manager) Update()
Update is a shorthand for [UpdateWithDelta](1.0/60.0).
func (*Manager) UpdateWithDelta ¶
UpdateWithDelta calls the Update methods on the entire scene tree.
First, it calls the bound [Controller.Update].
Then it calls the [Object.Update] methods on scene objects that are not disposed. The Update call order is identical to the AddObject order that was used before.
Disposed object are removed from the objects list.
type Object ¶
type Object interface {
// Init is called once when object is added to the scene.
//
// It's a good time to initialize all dependent objects
// and attach sprites to the scene.
Init(*Scene)
// IsDisposed reports whether scene object was disposed.
//
// Disposed objects are removed from the scene before their
// Update method is called for the current frame.
IsDisposed() bool
// Update is called for every object during every logical game frame.
// Delta is passed via the [Scene.Update] method.
// It could be a fixed value like 1.0/60 or a computed delta.
Update(delta float64)
}
Object is a scene-managed object those [Update] method will be called as a part of a game loop.
When its [IsDisposed] method returns true, it's removed from the scene.
type Scene ¶
type Scene struct {
// contains filtered or unexported fields
}
Scene creates a logical scope and lifetime for game objects and graphics.
Your root ebiten.Game will now only call the current scene's Update and Draw instead of trying to manage all the objects and graphics. (Note: you call these through the scene Manager.)
When the scene goes away, all scene-bound resources usually go away as well (unless you keep the pointer to them somewhere else). Therefore, you should avoid the unnecessary global state whether possible.
func (*Scene) AddGraphics ¶
AddGraphics adds the graphical object to the scene at the layer specified by its index.
func (*Scene) AddObject ¶
AddObject adds the logical object to the scene. Its [Object.Init] method will be called right away.
The [AddObject] method adds the object to the add-queue. The object will be actually added at the end of the current Update method's life cycle.
This object will be automatically removed from the scene when its [Object.IsDisposed] method reports true.
All added objects are stored inside the scene. If they're only reachable between each other and the scene, they can be easily garbage-collected as soon as this scene will be garbage-collected (there is usually only 1 active scene at a time).
func (*Scene) Controller ¶
func (s *Scene) Controller() Controller
Source Files