node

package
v0.0.0-...-5e2a49b Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 16, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Debug enables debug checks on tree operations.
	Debug bool

	// DebugCheckDisposed panics if a disposed node is used.
	DebugCheckDisposed func(n *Node, op string)

	// DebugCheckTreeDepth warns if tree depth exceeds a threshold.
	DebugCheckTreeDepth func(n *Node)

	// DebugCheckChildCount warns if a node has too many children.
	DebugCheckChildCount func(n *Node)

	// WhitePixelImage is the 1x1 white pixel used for solid color sprites.
	WhitePixelImage *ebiten.Image

	// InvalidateAncestorCacheFn walks up from n to the nearest cached ancestor
	// and marks it dirty (auto mode only). Wired by render/.
	InvalidateAncestorCacheFn func(n *Node)

	// RegisterAnimatedInCacheFn registers a node's cached command as animated
	// so replay reads the live TextureRegion. Wired by render/.
	RegisterAnimatedInCacheFn func(n *Node)

	// SetCacheAsTreeFn enables/disables subtree command caching. Wired by core/.
	SetCacheAsTreeFn func(n *Node, enabled bool, mode ...types.CacheTreeMode)

	// InvalidateCacheTreeFn marks a node's cache as stale. Wired by core/.
	InvalidateCacheTreeFn func(n *Node)

	// IsCacheAsTreeEnabledFn reports whether cache is enabled. Wired by core/.
	IsCacheAsTreeEnabledFn func(n *Node) bool

	// PropagatSceneFn recursively sets the scene back-pointer. Wired by core/.
	PropagateSceneFn func(n *Node, scene any)
)
View Source 
var AnyTransformDirty bool

AnyTransformDirty is set when any node's transform or alpha is dirtied. The scene resets this after the first UpdateWorldTransform pass and checks it before the second pass to skip a redundant full tree walk.

View Source 
var IdentityTransform = [6]float64{1, 0, 0, 1, 0, 0}

IdentityTransform is the identity affine matrix.

Functions

func ComputeLocalTransform 

func ComputeLocalTransform(n *Node) [6]float64

ComputeLocalTransform computes the local affine matrix from the node's transform properties. Returns [a, b, c, d, tx, ty].

func DefaultDebugCheckChildCount 

func DefaultDebugCheckChildCount(n *Node)

DefaultDebugCheckChildCount warns on stderr if a node has more than 1000 children.

func DefaultDebugCheckDisposed 

func DefaultDebugCheckDisposed(n *Node, op string)

DefaultDebugCheckDisposed panics if a disposed node is used in a tree operation.

func DefaultDebugCheckTreeDepth 

func DefaultDebugCheckTreeDepth(n *Node)

DefaultDebugCheckTreeDepth warns on stderr if tree depth exceeds threshold.

func InvertAffine 

func InvertAffine(m [6]float64) [6]float64

InvertAffine computes the inverse of a 2D affine matrix.

func IsAncestor 

func IsAncestor(candidate, node *Node) bool

IsAncestor reports whether candidate is an ancestor of node.

func MarkSubtreeDirty 

func MarkSubtreeDirty(n *Node)

MarkSubtreeDirty marks a node as needing transform and alpha recomputation.

func MatchPattern 

func MatchPattern(s, inner string, mode WildMode) bool

MatchPattern tests s against a parsed pattern.

func MultiplyAffine 

func MultiplyAffine(p, c [6]float64) [6]float64

MultiplyAffine multiplies two 2D affine matrices: result = parent * child.

func TransformPoint 

func TransformPoint(m [6]float64, x, y float64) (float64, float64)

TransformPoint applies an affine matrix to a point.

func UpdateWorldTransform 

func UpdateWorldTransform(n *Node, parentTransform [6]float64, parentAlpha float64, parentRecomputed bool, parentAlphaChanged bool)

UpdateWorldTransform recomputes a node's worldTransform and worldAlpha.

Types

type ClickContext 

type ClickContext struct {
	Node      *Node              // the clicked node
	EntityID  uint32             // the clicked node's EntityID (for ECS bridging)
	UserData  any                // the clicked node's UserData
	GlobalX   float64            // click X in world coordinates
	GlobalY   float64            // click Y in world coordinates
	LocalX    float64            // click X in the node's local coordinates
	LocalY    float64            // click Y in the node's local coordinates
	Button    types.MouseButton  // which mouse button was clicked
	PointerID int                // 0 = mouse, 1-9 = touch contacts
	Modifiers types.KeyModifiers // keyboard modifier keys held during the click
}

ClickContext carries click event data passed to click callbacks.

type DragContext 

type DragContext struct {
	Node         *Node              // the node being dragged
	EntityID     uint32             // the dragged node's EntityID (for ECS bridging)
	UserData     any                // the dragged node's UserData
	GlobalX      float64            // current pointer X in world coordinates
	GlobalY      float64            // current pointer Y in world coordinates
	LocalX       float64            // current pointer X in the node's local coordinates
	LocalY       float64            // current pointer Y in the node's local coordinates
	StartX       float64            // world X where the drag began
	StartY       float64            // world Y where the drag began
	DeltaX       float64            // X movement since the previous drag event
	DeltaY       float64            // Y movement since the previous drag event
	ScreenDeltaX float64            // X movement in screen pixels since the previous drag event
	ScreenDeltaY float64            // Y movement in screen pixels since the previous drag event
	Button       types.MouseButton  // which mouse button initiated the drag
	PointerID    int                // 0 = mouse, 1-9 = touch contacts
	Modifiers    types.KeyModifiers // keyboard modifier keys held during the drag
}

DragContext carries drag event data passed to drag callbacks.

type EmitFn 

type EmitFn func(n *Node, sceneRef any, viewWorld [6]float64, treeOrder *int)

EmitFn is the type for render emission functions stored on Node. The `any` parameter is an opaque *Scene — node/ never inspects it.

type MeshData 

type MeshData struct {
	Vertices         []ebiten.Vertex
	Indices          []uint16
	Image            *ebiten.Image
	TransformedVerts []ebiten.Vertex // preallocated transform buffer
	Aabb             types.Rect      // cached local-space AABB
	AabbDirty        bool            // recompute AABB when true
}

MeshData holds mesh-specific fields for NodeTypeMesh nodes. Allocated by NewMesh. Only mesh nodes carry this data.

type Node 

type Node struct {
	// ---- HOT: traverse flags (cache line 0) ----
	Visible_       bool
	Renderable_    bool
	TransformDirty bool
	AlphaDirty     bool
	ChildrenSorted bool
	Type           types.NodeType
	RenderLayer    uint8
	BlendMode_     types.BlendMode

	// ---- HOT: computed world state ----
	WorldAlpha     float64
	Alpha_         float64
	WorldTransform [6]float64

	// ---- HOT: children for iteration ----
	Children_      []*Node
	SortedChildren []*Node

	// ---- HOT: render command fields ----
	CustomImage_   *ebiten.Image
	CacheData      any // opaque *render.CacheTreeData — node/ never inspects
	GlobalOrder    int
	TextureRegion_ types.TextureRegion
	Color_         types.Color

	// ---- WARM: local transform ----
	X_, Y_         float64
	ScaleX_        float64
	ScaleY_        float64
	Rotation_      float64
	SkewX_, SkewY_ float64
	PivotX_        float64
	PivotY_        float64

	// ---- COLD: hierarchy, identity, metadata ----
	Parent   *Node
	Scene_   any // opaque *Scene — node/ never inspects
	Name     string
	UserData any

	// ---- COLD: pointers ----
	Mesh         *MeshData
	Emitter      *particle.Emitter
	TextBlock    *text.TextBlock
	Callbacks    *NodeCallbacks
	MaskNode     *Node
	CacheTexture *ebiten.Image

	// ---- COLD: interfaces and slices ----
	HitShape types.HitShape
	Filters  []any // opaque []filter.Filter — node/ never inspects

	// ---- COLD: functions ----
	OnUpdate   func(dt float64)
	CustomEmit func(s any, treeOrder *int)
	EmitFn     EmitFn

	// ---- COLD: int-sized ----
	ZIndex_  int
	ID       uint32
	EntityID uint32

	// ---- COLD: bools (packed) ----
	Interactable bool
	Draggable    bool
	Pinchable    bool
	CacheEnabled bool
	CacheDirty   bool
	Disposed     bool
}

Node is the fundamental scene graph element. A single flat struct is used for all node types to avoid interface dispatch on the hot path.

func NewNode 

func NewNode(name string, nodeType types.NodeType) *Node

NewNode creates a Node with default field values.

func (*Node) AddChild 

func (n *Node) AddChild(child *Node)

AddChild appends child to this node's children. If child already has a parent, it is removed from that parent first.

func (*Node) AddChildAt 

func (n *Node) AddChildAt(child *Node, index int)

AddChildAt inserts child at the given index.

func (*Node) Alpha 

func (n *Node) Alpha() float64

func (*Node) BlendMode 

func (n *Node) BlendMode() types.BlendMode

func (*Node) ChildAt 

func (n *Node) ChildAt(index int) *Node

ChildAt returns the child at the given index.

func (*Node) Children 

func (n *Node) Children() []*Node

Children returns the child list.

func (*Node) ClearMask 

func (n *Node) ClearMask()

func (*Node) Color 

func (n *Node) Color() types.Color

func (*Node) CustomImage 

func (n *Node) CustomImage() *ebiten.Image

func (*Node) Dispose 

func (n *Node) Dispose()

func (*Node) EnsureCallbacks 

func (n *Node) EnsureCallbacks() *NodeCallbacks

EnsureCallbacks lazily allocates the callback struct.

func (*Node) EnsureMesh 

func (n *Node) EnsureMesh() *MeshData

func (*Node) FindChild 

func (n *Node) FindChild(pattern string) *Node

FindChild returns the first direct child matching the name pattern, or nil.

func (*Node) FindDescendant 

func (n *Node) FindDescendant(pattern string) *Node

FindDescendant returns the first descendant (depth-first) matching the name pattern.

func (*Node) GetMask 

func (n *Node) GetMask() *Node

func (*Node) GetOnClick 

func (n *Node) GetOnClick() func(ClickContext)

func (*Node) GetOnDrag 

func (n *Node) GetOnDrag() func(DragContext)

func (*Node) GetOnDragEnd 

func (n *Node) GetOnDragEnd() func(DragContext)

func (*Node) GetOnDragStart 

func (n *Node) GetOnDragStart() func(DragContext)

func (*Node) GetOnPinch 

func (n *Node) GetOnPinch() func(PinchContext)

func (*Node) GetOnPointerDown 

func (n *Node) GetOnPointerDown() func(PointerContext)

func (*Node) GetOnPointerEnter 

func (n *Node) GetOnPointerEnter() func(PointerContext)

func (*Node) GetOnPointerLeave 

func (n *Node) GetOnPointerLeave() func(PointerContext)

func (*Node) GetOnPointerMove 

func (n *Node) GetOnPointerMove() func(PointerContext)

func (*Node) GetOnPointerUp 

func (n *Node) GetOnPointerUp() func(PointerContext)

func (*Node) HasOnClick 

func (n *Node) HasOnClick() bool

HasOnClick reports whether a click callback is registered.

func (*Node) HasOnDrag 

func (n *Node) HasOnDrag() bool

HasOnDrag reports whether a drag callback is registered.

func (*Node) HasOnDragEnd 

func (n *Node) HasOnDragEnd() bool

HasOnDragEnd reports whether a drag-end callback is registered.

func (*Node) HasOnDragStart 

func (n *Node) HasOnDragStart() bool

HasOnDragStart reports whether a drag-start callback is registered.

func (*Node) HasOnPinch 

func (n *Node) HasOnPinch() bool

HasOnPinch reports whether a pinch callback is registered.

func (*Node) HasOnPointerDown 

func (n *Node) HasOnPointerDown() bool

HasOnPointerDown reports whether a pointer-down callback is registered.

func (*Node) HasOnPointerEnter 

func (n *Node) HasOnPointerEnter() bool

HasOnPointerEnter reports whether a pointer-enter callback is registered.

func (*Node) HasOnPointerLeave 

func (n *Node) HasOnPointerLeave() bool

HasOnPointerLeave reports whether a pointer-leave callback is registered.

func (*Node) HasOnPointerMove 

func (n *Node) HasOnPointerMove() bool

HasOnPointerMove reports whether a pointer-move callback is registered.

func (*Node) HasOnPointerUp 

func (n *Node) HasOnPointerUp() bool

HasOnPointerUp reports whether a pointer-up callback is registered.

func (*Node) Height 

func (n *Node) Height() float64

func (*Node) Invalidate 

func (n *Node) Invalidate()

Invalidate marks the node's transform and alpha as dirty.

func (*Node) InvalidateCache 

func (n *Node) InvalidateCache()

func (*Node) InvalidateCacheTree 

func (n *Node) InvalidateCacheTree()

func (*Node) InvalidateMeshAABB 

func (n *Node) InvalidateMeshAABB()

func (*Node) IsCacheAsTreeEnabled 

func (n *Node) IsCacheAsTreeEnabled() bool

func (*Node) IsCacheEnabled 

func (n *Node) IsCacheEnabled() bool

func (*Node) IsDisposed 

func (n *Node) IsDisposed() bool

func (*Node) LocalToWorld 

func (n *Node) LocalToWorld(lx, ly float64) (wx, wy float64)

func (*Node) MeshImage 

func (n *Node) MeshImage() *ebiten.Image

func (*Node) MeshIndices 

func (n *Node) MeshIndices() []uint16

func (*Node) MeshVertices 

func (n *Node) MeshVertices() []ebiten.Vertex

func (*Node) NumChildren 

func (n *Node) NumChildren() int

NumChildren returns the number of children.

func (*Node) OnClick 

func (n *Node) OnClick(fn func(ClickContext))

func (*Node) OnDrag 

func (n *Node) OnDrag(fn func(DragContext))

func (*Node) OnDragEnd 

func (n *Node) OnDragEnd(fn func(DragContext))

func (*Node) OnDragStart 

func (n *Node) OnDragStart(fn func(DragContext))

func (*Node) OnPinch 

func (n *Node) OnPinch(fn func(PinchContext))

func (*Node) OnPointerDown 

func (n *Node) OnPointerDown(fn func(PointerContext))

func (*Node) OnPointerEnter 

func (n *Node) OnPointerEnter(fn func(PointerContext))

func (*Node) OnPointerLeave 

func (n *Node) OnPointerLeave(fn func(PointerContext))

func (*Node) OnPointerMove 

func (n *Node) OnPointerMove(fn func(PointerContext))

func (*Node) OnPointerUp 

func (n *Node) OnPointerUp(fn func(PointerContext))

func (*Node) PivotX 

func (n *Node) PivotX() float64

func (*Node) PivotY 

func (n *Node) PivotY() float64

func (*Node) RemoveChild 

func (n *Node) RemoveChild(child *Node)

RemoveChild detaches child from this node.

func (*Node) RemoveChildAt 

func (n *Node) RemoveChildAt(index int) *Node

RemoveChildAt removes and returns the child at the given index.

func (*Node) RemoveChildren 

func (n *Node) RemoveChildren()

RemoveChildren detaches all children from this node.

func (*Node) RemoveFromParent 

func (n *Node) RemoveFromParent()

RemoveFromParent detaches this node from its parent.

func (*Node) Renderable 

func (n *Node) Renderable() bool

func (*Node) Rotation 

func (n *Node) Rotation() float64

func (*Node) ScaleX 

func (n *Node) ScaleX() float64

func (*Node) ScaleY 

func (n *Node) ScaleY() float64

func (*Node) Scene 

func (n *Node) Scene() any

Scene returns the Scene this node belongs to, or nil if not in a scene graph. Returns any because node/ cannot import the root package. Callers in root should type-assert to *Scene.

func (*Node) SetAlign 

func (n *Node) SetAlign(a types.TextAlign)

func (*Node) SetAlpha 

func (n *Node) SetAlpha(a float64)

func (*Node) SetBlendMode 

func (n *Node) SetBlendMode(b types.BlendMode)

func (*Node) SetCacheAsTexture 

func (n *Node) SetCacheAsTexture(enabled bool)

func (*Node) SetCacheAsTree 

func (n *Node) SetCacheAsTree(enabled bool, mode ...types.CacheTreeMode)

func (*Node) SetChildIndex 

func (n *Node) SetChildIndex(child *Node, index int)

SetChildIndex moves child to a new index among its siblings.

func (*Node) SetColor 

func (n *Node) SetColor(c types.Color)

func (*Node) SetContent 

func (n *Node) SetContent(s string)

func (*Node) SetCustomImage 

func (n *Node) SetCustomImage(img *ebiten.Image)

func (*Node) SetFont 

func (n *Node) SetFont(f interface {
	MeasureString(string) (float64, float64)
	LineHeight() float64
})

func (*Node) SetFontSize 

func (n *Node) SetFontSize(size float64)

func (*Node) SetGlobalOrder 

func (n *Node) SetGlobalOrder(o int)

func (*Node) SetLineHeight 

func (n *Node) SetLineHeight(h float64)

func (*Node) SetMask 

func (n *Node) SetMask(maskNode *Node)

func (*Node) SetMeshData 

func (n *Node) SetMeshData(vertices []ebiten.Vertex, indices []uint16, img *ebiten.Image)

func (*Node) SetMeshImage 

func (n *Node) SetMeshImage(img *ebiten.Image)

func (*Node) SetMeshIndices 

func (n *Node) SetMeshIndices(indices []uint16)

func (*Node) SetMeshVertices 

func (n *Node) SetMeshVertices(vertices []ebiten.Vertex)

func (*Node) SetPivot 

func (n *Node) SetPivot(px, py float64)

func (*Node) SetPosition 

func (n *Node) SetPosition(x, y float64)

func (*Node) SetRenderLayer 

func (n *Node) SetRenderLayer(l uint8)

func (*Node) SetRenderable 

func (n *Node) SetRenderable(r bool)

func (*Node) SetRotation 

func (n *Node) SetRotation(r float64)

func (*Node) SetScale 

func (n *Node) SetScale(sx, sy float64)

func (*Node) SetSize 

func (n *Node) SetSize(w, h float64)

func (*Node) SetSkew 

func (n *Node) SetSkew(sx, sy float64)

func (*Node) SetTextColor 

func (n *Node) SetTextColor(c types.Color)

func (*Node) SetTextEffects 

func (n *Node) SetTextEffects(e *text.TextEffects)

func (*Node) SetTextureRegion 

func (n *Node) SetTextureRegion(r types.TextureRegion)

func (*Node) SetVisible 

func (n *Node) SetVisible(v bool)

func (*Node) SetWrapWidth 

func (n *Node) SetWrapWidth(w float64)

func (*Node) SetX 

func (n *Node) SetX(x float64)

func (*Node) SetY 

func (n *Node) SetY(y float64)

func (*Node) SetZIndex 

func (n *Node) SetZIndex(z int)

func (*Node) SkewX 

func (n *Node) SkewX() float64

func (*Node) SkewY 

func (n *Node) SkewY() float64

func (*Node) TextureRegion 

func (n *Node) TextureRegion() types.TextureRegion

func (*Node) Visible 

func (n *Node) Visible() bool

func (*Node) Width 

func (n *Node) Width() float64

func (*Node) WorldToLocal 

func (n *Node) WorldToLocal(wx, wy float64) (lx, ly float64)

func (*Node) X 

func (n *Node) X() float64

func (*Node) Y 

func (n *Node) Y() float64

func (*Node) ZIndex 

func (n *Node) ZIndex() int

type NodeCallbacks 

type NodeCallbacks struct {
	OnPointerDown  func(PointerContext)
	OnPointerUp    func(PointerContext)
	OnPointerMove  func(PointerContext)
	OnClick        func(ClickContext)
	OnDragStart    func(DragContext)
	OnDrag         func(DragContext)
	OnDragEnd      func(DragContext)
	OnPinch        func(PinchContext)
	OnPointerEnter func(PointerContext)
	OnPointerLeave func(PointerContext)
}

NodeCallbacks holds per-node event handler functions. Allocated on first callback setter call. Most nodes never receive callbacks.

type NodeIndex 

type NodeIndex struct {
	// contains filtered or unexported fields
}

NodeIndex is an opt-in registry for looking up nodes by name or tag.

func NewNodeIndex 

func NewNodeIndex() *NodeIndex

NewNodeIndex creates an empty NodeIndex.

func (*NodeIndex) Add 

func (idx *NodeIndex) Add(node *Node, tags ...string)

Add registers a node in the index.

func (*NodeIndex) CountByTag 

func (idx *NodeIndex) CountByTag(tag string) int

CountByTag returns the number of nodes with the given tag.

func (*NodeIndex) Each 

func (idx *NodeIndex) Each(fn func(n *Node) bool)

Each iterates all registered nodes. Return false from fn to stop early.

func (*NodeIndex) EachByTag 

func (idx *NodeIndex) EachByTag(tag string, fn func(n *Node) bool)

EachByTag iterates nodes with the given tag.

func (*NodeIndex) FindAllByName 

func (idx *NodeIndex) FindAllByName(pattern string) []*Node

FindAllByName returns all registered nodes matching the name pattern.

func (*NodeIndex) FindByName 

func (idx *NodeIndex) FindByName(pattern string) *Node

FindByName returns the first registered node matching the name pattern.

func (*NodeIndex) FindByTag 

func (idx *NodeIndex) FindByTag(pattern string) []*Node

FindByTag returns all nodes with the given tag pattern.

func (*NodeIndex) FindByTags 

func (idx *NodeIndex) FindByTags(tags ...string) []*Node

FindByTags returns all nodes that have every one of the given tags.

func (*NodeIndex) Remove 

func (idx *NodeIndex) Remove(node *Node, tags ...string)

Remove removes tags from a node. If no tags are provided, the node is unregistered entirely.

type PinchContext 

type PinchContext struct {
	CenterX, CenterY   float64 // midpoint between the two touch points in world coordinates
	Scale, ScaleDelta  float64 // cumulative scale factor and frame-to-frame change
	Rotation, RotDelta float64 // cumulative rotation (radians) and frame-to-frame change
}

PinchContext carries two-finger pinch/rotate gesture data.

type PointerContext 

type PointerContext struct {
	Node      *Node              // the node under the pointer, or nil if none
	EntityID  uint32             // the hit node's EntityID (for ECS bridging)
	UserData  any                // the hit node's UserData
	GlobalX   float64            // pointer X in world coordinates
	GlobalY   float64            // pointer Y in world coordinates
	LocalX    float64            // pointer X in the hit node's local coordinates
	LocalY    float64            // pointer Y in the hit node's local coordinates
	Button    types.MouseButton  // which mouse button is involved
	PointerID int                // 0 = mouse, 1-9 = touch contacts
	Modifiers types.KeyModifiers // keyboard modifier keys held during the event
}

PointerContext carries pointer event data passed to pointer callbacks.

type WildMode 

type WildMode byte

WildMode describes the type of % wildcard match. 

const (
	WildNone     WildMode = iota // exact match
	WildPrefix                   // "foo%" — starts with
	WildSuffix                   // "%foo" — ends with
	WildContains                 // "%foo%" — contains
)

func ParsePattern 

func ParsePattern(pattern string) (inner string, mode WildMode)

ParsePattern checks for % wildcards at the start/end of pattern.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.