Groups 与 Autoload

sapling2d 不支持按路径查找节点。父节点引用自己的子节点用字段；跨层级找一类节点用 Groups；跨场景存在的全局单例用 Autoload。

import { Node, Node2D, Scene, v } from 'sapling2d'

class Coin extends Node2D {
  value = 1
}

/** 全局单例：跨场景保留，用类型取出 */
class GameState extends Node {
  coins = 0
}

// 声明合并：注册之后组名有补全、写错是类型错误，getNodesInGroup 返回 Coin[]
declare module 'sapling2d' {
  interface GroupRegistry {
    coins: Coin
  }
}

export class Level extends Scene {
  override ready() {
    for (let i = 0; i < 3; i++) this.add(new Coin({ position: v(100 * i, 0), groups: ['coins'] }))
  }

  collectAll() {
    const state = this.tree.autoload(GameState)
    for (const coin of this.tree.getNodesInGroup('coins')) {
      state.coins += coin.value
      coin.queueFree()
    }
  }
}

// 启动参数里注册：startGame({ main: Level, autoloads: [GameState] })

Groups

• 节点通过构造参数 groups: ['coins'] 或 addToGroup 加入组，this.tree.getNodesInGroup('coins') 取出组里的所有节点。
• 用声明合并给组名登记类型：declare module 'sapling2d' { interface GroupRegistry { coins: Coin } }。之后组名有补全，写错是类型错误，getNodesInGroup 直接返回 Coin[]。

Autoload

• Autoload 是跨场景存在的节点，适合放分数、金币、设置这类全局状态。
• 在启动参数里注册：startGame({ main: Level, autoloads: [GameState] })。
• 按类型取出：this.tree.autoload(GameState)，返回值带类型。