gaesup-world: Skill for Claude Code

도메인 추가/확장 절차

참조 구현: src/core/motions/ (가장 완성도 높은 도메인 — PhysicsSystem, MotionSystem, MotionBridge). 새 코드를 쓰기 전에 대응되는 motions 파일을 먼저 읽고 패턴을 복제할 것.

폴더 템플릿

src/core/<domain>/
  core/        # Layer 1: 순수 엔진. react/zustand/@react-three/fiber import 금지(ESLint 차단). three/rapier 허용.
  bridge/      # Layer 2: CoreBridge 상속. types.ts에 Entity/Snapshot/Command 타입.
  hooks/       # Layer 3: use<Thing>.ts
  components/  # Layer 3: <Name>/{index.tsx, styles.css, types.ts}
  stores/      # <name>Store.ts 또는 slices/<name>/{slice.ts,types.ts}
  __tests__/   # 테스트명 한글, 코드 옆 배치
  types.ts  index.ts  plugin.ts

Layer 2 브리지 계약 (실제 시그니처)

CoreBridge<EngineType extends IDisposable, SnapshotType, CommandType> 상속 후 추상 메서드 3개만 구현:

@DomainBridge('<domain>')
@EnableEventLog()
export class FooBridge extends CoreBridge<FooEntity, FooSnapshot, FooCommand> {
  private tempQuaternion = new THREE.Quaternion();
  protected buildEngine(id: string, ...args: RuntimeValue[]): FooEntity | null { /* null 반환 = 등록 거부 */ }
  @ValidateCommand()
  protected executeCommand(entity: FooEntity, command: FooCommand, id: string): void { /* command.type별 switch */ }
  protected createSnapshot(entity: FooEntity, id: string): FooSnapshot | null { /* 아래 할당 규칙 필수 */ }
}

• 스냅샷 할당 규칙: getCachedSnapshot(id)로 가져와 in-place 갱신(snapshot.position.set(...)), 없을 때만 생성 후 cacheSnapshot(id, s). createSnapshot은 프레임마다 불리므로 내부에서 new THREE.* 금지 — 임시 객체는 클래스 필드로 재사용(MotionBridge.tempQuaternion 참조).
• System 인스턴스 생성 시 DI 주입: DIContainer.getInstance().injectProperties(system). buildEngine이 반환하는 엔티티는 dispose()를 반드시 포함.
• 브리지가 앱 시작 시 필요하면 src/core/initializeBridges.ts에 import 한 줄 추가(등록만 — BridgeFactory가 lazy getOrCreate).
• 사용 가능한 데코레이터: @DomainBridge(name), @EnableEventLog(), @ValidateCommand(), @LogSnapshot(), @Profile(), @HandleError(), @ManageRuntime({ autoStart }) (boilerplate/decorators).

Layer 3 소비 계약

const entity = useManagedEntity(bridge, id, rigidBodyRef, {
  onInit, onDispose, frameCallback, priority, throttle, skipWhenHidden, enabled, dependencies,
});