class Eagle::Node

Overview

The building block of Eagle's scene tree. Everything in a scene is a node: sprites, cameras, bodies, sounds, UI widgets and your own game objects.

Nodes form a tree. Adding a node under SceneTree.root (directly or through a parent) brings it to life, and Eagle then calls its hooks:

Subclass a node type and override the hooks you need. Plain Node has no position; use Node2D or Node3D for things that live in space.

class Blinker < Node2D
  @t = 0.0

  def ready : Nil
    add(Label.new("hello"))
  end

  def process(dt : Float32) : Nil
    @t += dt
    self.visible = @t % 1 < 0.5
    queue_free if @t > 10
  end
end

blinker = Blinker.new
blinker.position = v2(200, 100)
SceneTree.root.add(blinker)

Nodes are found by name with #get_node("Player/Sprite"), by type with #find_all, and by group with #add_to_group plus SceneTree.group.

Direct Known Subclasses

Defined in:

eagle/core/node.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(name : String = "") #

Creates a node. When name is empty, the class name is used.


Instance Method Detail

def <<(child : Node) : self #

Adds child and returns self, so additions can be chained.


def [](path : String) : Node #

Short form of #get_node.


def []?(path : String) : Node | Nil #

Short form of #get_node?.


def add(child : Node) : Node #

--- tree manipulation ---------------------------------------------------- Adds child as the last child and returns it. If this node is in the tree, the child enters too and gets #ready. Raises if child already has a parent.

enemy = Node2D.new("Enemy")
SceneTree.root.add(enemy).add(Sprite2D.new(Texture.new(Image.circle(8, Color::RED))))

def add(*children : Node) : Nil #

Adds several children in order.


def add_child(child : Node) : Node #

Same as #add, for readers coming from Godot.


def add_to_group(group : String) : self #

--- groups --------------------------------------------------------------- Adds this node to a named group and returns self. Groups make it easy to act on many nodes at once with SceneTree.group and SceneTree.call_group.


def ancestor_of?(node : Node) : Bool #

True when node is somewhere below this one.


def can_process? : Bool #

--- processing ----------------------------------------------------------- True when this node should run #process right now, given pause state and #process_mode.


def child?(name : String) : Node | Nil #

The direct child called name, or nil.


def child_added : Eagle::Emitter(Node) #

Emitted after a child is added, with the child.


def child_count : Int32 #

Number of direct children.


def child_removed : Eagle::Emitter(Node) #

Emitted after a child is removed, with the child.


def children : Array(Eagle::Node) #

Child nodes in the order they were added.


def children_of(type : T.class) : Array(T) forall T #

Direct children of the given type.


def clear_children : Nil #

Removes every child.


def draw(g : Graphics) : Nil #

Draws this node. Node2D has already applied its transform, so draw around (0, 0).


def dump(io : IO = STDOUT, indent = 0) : Nil #

Prints the subtree with indentation, which is handy when debugging.


def each_ancestor(& : Node -> ) : Nil #

Yields the parent, then its parent, up to the root.


def each_child(& : Node -> ) : Nil #

Yields each direct child.


def each_descendant(&block : Node -> ) : Nil #

Yields every descendant, depth-first.


def emit_child_added(*args) : Nil #

Emitted after a child is added, with the child.


def emit_child_removed(*args) : Nil #

Emitted after a child is removed, with the child.


def emit_tree_entered(*args) : Nil #

Emitted each time the node enters the tree. Connect with on_tree_entered { ... }.


def emit_tree_exited(*args) : Nil #

Emitted each time the node leaves the tree.


def enter_tree : Nil #

Called every time the node is attached to the tree, before #ready.


def exit_tree : Nil #

Called every time the node leaves the tree. Undo anything #enter_tree did.


def find(name : String) : Node | Nil #

The first descendant with this name, searched depth-first.


def find_all(type : T.class) : Array(T) forall T #

Every descendant of the given type.

SceneTree.root.find_all(Sprite2D).each { |s| s.modulate = Color::RED }

def first_child : Node | Nil #

The first child, or nil.


def free : Nil #

Removes this node right away. Prefer #queue_free from inside callbacks.


def get_node(path : String, type : T.class) : T forall T #

Finds a node by path and casts it, so you get a typed result.

class Player < Node2D
  def ready : Nil
    add(Label.new("P1", name: "Tag"))
    get_node("Tag", Label).text = "Player 1"
  end
end

def get_node(path : String) : Node #

Finds a node by path and raises if it doesn't exist.


def get_node?(path : String) : Node | Nil #

Finds a node by path, or returns nil. Paths work like file paths: "Sprite", "Player/Gun", "../Sibling", and "/root/Hud" from the top.


def groups : Set(String) #

Names of the groups this node belongs to.


def in_group?(group : String) : Bool #

True when this node belongs to group.


def in_tree? : Bool #

True while the node is attached, directly or indirectly, to SceneTree.root.


def input(event : Event) : Nil #

Receives input events. Set event.handled = true to stop them from reaching other nodes.


def name : String #

The node's name, used by #get_node paths. Defaults to the class name.


def name=(name : String) #

The node's name, used by #get_node paths. Defaults to the class name.


def on_child_added(&block : Node -> Nil) : Proc(Node, Nil) #

Emitted after a child is added, with the child.


def on_child_removed(&block : Node -> Nil) : Proc(Node, Nil) #

Emitted after a child is removed, with the child.


def on_tree_entered(&block : -> Nil) : Proc(Nil) #

Emitted each time the node enters the tree. Connect with on_tree_entered { ... }.


def on_tree_exited(&block : -> Nil) : Proc(Nil) #

Emitted each time the node leaves the tree.


def parent : Node | Nil #

The parent node, or nil if this node hasn't been added anywhere.


def path : String #

The node's path from the root, such as "/root/Level/Player".


def physics_process(dt : Float32) : Nil #

Called at the fixed rate (Config#fixed_fps), after the physics world steps. Move physics bodies and read contacts here.


def process(dt : Float32) : Nil #

Called every frame with the frame time in seconds. Put per-frame logic here.


def process_mode : Eagle::Node::ProcessMode #

Controls behavior while the tree is paused; see ProcessMode.


def process_mode=(process_mode : Eagle::Node::ProcessMode) #

Controls behavior while the tree is paused; see ProcessMode.


def queue_free : Nil #

Removes this node at the end of the frame. This is the safe way for a node to delete itself from inside #process, a signal handler or a collision callback.


def queued_free? : Bool #

True after #queue_free and before the removal happens.


def ready : Nil #

--- overridable hooks ---------------------------------------------------- Called once, the first time this node enters the tree, after its children are ready. Build child nodes, look up siblings and connect signals here.


def ready_called? : Bool #

True once #ready has run. It runs only the first time the node enters the tree.


def remove(child : Node) : Nil #

Detaches child right away. It leaves the tree and gets #exit_tree. You can add it again later.


def remove_child(child : Node) : Nil #

Same as #remove.


def remove_from_group(group : String) : Nil #

Removes this node from a group.


def remove_from_parent : Nil #

Detaches this node from its parent right away.


def resized(width : Int32, height : Int32) : Nil #

Called on every node in the tree when the window is resized.


def root : Node #

The topmost ancestor. It is SceneTree.root when the node is in the tree.


def to_s(io : IO) : Nil #
Description copied from class Reference

Appends a short String representation of this object which includes its class name and its object address.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).to_s # => #<Person:0x10a199f20>

def tree_entered : Eagle::Emitter() #

Emitted each time the node enters the tree. Connect with on_tree_entered { ... }.


def tree_exited : Eagle::Emitter() #

Emitted each time the node leaves the tree.


def visible=(visible : Bool) #

Hidden nodes and their children are not drawn. They still process.


def visible? : Bool #

Hidden nodes and their children are not drawn. They still process.


def z_index : Int32 #

Draw order among siblings: higher values draw later, on top.


def z_index=(z_index : Int32) #

Draw order among siblings: higher values draw later, on top.