gdscript-patterns

GDScript Patterns for Onyx Engine

When writing GDScript for Onyx Engine projects, follow these patterns. They align with Godot 4.x conventions and work well with MCP scene operations.

Type Hints

Always use type hints for clarity and editor support:

var health: int = 100
var speed: float = 5.0
var player_name: String = ""
var velocity: Vector3 = Vector3.ZERO
var is_alive: bool = true

For nodes, use typed references:

@onready var collision_shape: CollisionShape3D = $CollisionShape3D
@onready var camera: Camera3D = $Camera3D

Signals

Define signals at the top of the script, then emit them:

signal died
signal health_changed(new_health: int)
signal item_collected(item_name: String)

func take_damage(amount: int) -> void:
    health -= amount
    health_changed.emit(health)
    if health <= 0:
        died.emit()

When connecting via MCP, use onyx_connect_signal with the emitter path, signal name, receiver path, and method name. The receiver script must have the method defined.

Exports

Use @export for inspector-editable properties:

@export var move_speed: float = 5.0
@export var jump_force: float = 10.0
@export var max_health: int = 100
@export var can_double_jump: bool = false

Exports appear in the inspector. MCP can set initial values via onyx_set_prop after the node exists, but exports are best for values the designer tweaks.

Lifecycle Methods

Method	When it runs	Use for
_ready()	Once when node enters tree	Initialization, getting node references
_process(delta: float)	Every frame	UI, non-physics logic
_physics_process(delta: float)	Every physics frame (fixed)	Movement, physics, collision

For character movement, use _physics_process and move_and_slide().

Node Access

# Prefer $ for direct children
var camera = $Camera3D

# get_node() for dynamic paths
var target = get_node("../Enemy/HealthBar")

# get_parent() / get_children() when needed
var siblings = get_parent().get_children()