forge3d.scene — Scene Management¶

The scene module provides hierarchical scene nodes, prefab templates, and a scene manager for organizing complex game worlds.

Classes¶

SceneNode ¶

씬 계층 트리의 단일 노드.

ECS Transform을 감싸 부모/자식 계층을 관리하고 월드 행렬을 dirty flag로 캐시한다.

world_matrix ¶

world_matrix() -> np.ndarray

(4,4) 월드 변환 행렬 (dirty flag 캐시).

find ¶

find(name: str) -> SceneNode | None

이름으로 자신 또는 하위 노드를 검색한다.

descendants ¶

descendants() -> list[SceneNode]

자신을 포함한 모든 하위 노드 리스트.

Prefab ¶

재사용 가능한 엔티티+컴포넌트 묶음 템플릿.

JSON 파일에서 로드하거나 SceneNode 트리에서 생성할 수 있다.

save `staticmethod` ¶

save(node: SceneNode, path: str | Path) -> None

SceneNode 트리를 JSON Prefab 파일로 저장한다.

load `staticmethod` ¶

load(path: str | Path) -> Prefab

JSON 파일에서 Prefab을 로드한다.

instantiate ¶

instantiate(ew: EntityWorld, position: ndarray | None = None, rotation: ndarray | None = None) -> SceneNode

Prefab을 EntityWorld에 인스턴스화하고 SceneNode 트리를 반환한다.

SceneManager ¶

씬 파일의 로드·언로드를 관리하는 싱글톤 스타일 매니저.

씬 파일 = P27 save_scene() 포맷의 JSON.

entity_count `property` ¶

entity_count: int

현재 씬의 살아있는 엔티티 수.

load_scene ¶

load_scene(path: str) -> None

현재 씬을 언로드하고 새 씬을 로드한다.

add_scene ¶

add_scene(path: str) -> None

현재 씬에 중첩(additive)으로 씬을 추가한다.

unload_scene ¶

unload_scene() -> None

현재 씬의 모든 엔티티를 소멸시킨다.

on_scene_loaded ¶

on_scene_loaded(callback: Callable) -> None

씬 로드 완료 후 호출될 콜백을 등록한다.

on_scene_unloading ¶

on_scene_unloading(callback: Callable) -> None

씬 언로드 시작 전 호출될 콜백을 등록한다.

Usage examples¶

Build a scene hierarchy¶

import forge3d as f3d
import numpy as np

sm = f3d.SceneManager()
world = f3d.World()

# Root node (the scene root is always implicitly present)
root = sm.root

# Create a car node
car_node = f3d.SceneNode(name="car")
car_node.position = np.array([0.0, 0.0, 0.5])
sm.add(car_node, parent=root)

# Attach wheels as children — they inherit the car's transform
for i, offset in enumerate([( 1.2, 0.6, 0), ( 1.2, -0.6, 0),
                              (-1.2, 0.6, 0), (-1.2, -0.6, 0)]):
    wheel = f3d.SceneNode(name=f"wheel_{i}")
    wheel.position = np.array(offset)
    sm.add(wheel, parent=car_node)

Prefab — reusable entity template¶

# Define a tree prefab once
tree_prefab = f3d.Prefab(name="pine_tree")
tree_prefab.add_body(
    shape=f3d.Shape.box(size=(0.3, 0.3, 3.0)),
    material=f3d.Material(color=(0.4, 0.25, 0.1)),  # trunk
)
tree_prefab.add_body(
    shape=f3d.Shape.box(size=(2.0, 2.0, 2.5)),
    material=f3d.Material(color=(0.1, 0.5, 0.15)),  # canopy
    offset=(0, 0, 2.5),
)
sm.register_prefab(tree_prefab)

# Instantiate many trees
for i in range(20):
    x = np.random.uniform(-30, 30)
    y = np.random.uniform(-30, 30)
    sm.instantiate("pine_tree", position=(x, y, 0), world=world)

Scene manager queries¶

# Find a node by name
car = sm.find("car")
print(car.world_position)    # absolute world-space position

# Find all nodes matching a tag
enemies = sm.find_all_by_tag("enemy")

# Destroy a node (and its children)
sm.destroy(car)

Scene serialization¶

# Save the scene graph
sm.save("scene.json")

# Load it back
sm2 = f3d.SceneManager()
sm2.load("scene.json")