pyforge3d 1.0.0__tar.gz

pyforge3d-1.0.0/.claude/settings.json

@@ -0,0 +1,66 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir -p /workspaces/2026_python_toy_project_1/src/forge3d/io /workspaces/2026_python_toy_project_1/assets/models)",
+      "Bash(python -c \"import forge3d; print\\('forge3d import OK, version:', forge3d.__version__\\)\")",
+      "Bash(python -c ' *)",
+      "Bash(python -m pytest tests/test_import.py tests/test_backend.py tests/test_math.py tests/test_collision.py tests/test_snapshot.py tests/test_realtime_smoke.py tests/test_contact_physics.py tests/test_api_usability.py -q --tb=short)",
+      "Bash(python -m pytest tests/test_import.py tests/test_backend.py tests/test_math.py tests/test_collision.py tests/test_snapshot.py tests/test_contact_physics.py tests/test_api_usability.py -q --tb=short)",
+      "Bash(python -m pytest tests/test_realtime_smoke.py tests/test_hq_renderer.py -q --tb=short)",
+      "Bash(python -m pytest tests/test_rnea_2dof.py tests/test_crba.py tests/test_aba.py tests/test_conservation.py tests/test_p12_friction.py tests/test_p13_rigid_body.py tests/test_robot.py tests/test_collision.py -q --tb=short)",
+      "Bash(python -m pytest tests/test_mesh_and_io.py -q --tb=short)",
+      "Bash(python -m ruff check src/forge3d/io/ src/forge3d/collision/epa.py src/forge3d/collision/gjk.py src/forge3d/collision/detection.py src/forge3d/sim/world.py src/forge3d/render/realtime/ src/forge3d/facade.py src/forge3d/__init__.py)",
+      "Bash(python -m ruff check --fix src/forge3d/io/ src/forge3d/collision/epa.py src/forge3d/collision/gjk.py src/forge3d/collision/detection.py src/forge3d/sim/world.py src/forge3d/render/realtime/ src/forge3d/facade.py src/forge3d/__init__.py)",
+      "Bash(python -m ruff format --check src/forge3d/io/ src/forge3d/collision/epa.py src/forge3d/collision/detection.py src/forge3d/sim/world.py src/forge3d/render/realtime/ src/forge3d/facade.py)",
+      "Bash(python -m ruff format src/forge3d/io/ src/forge3d/collision/epa.py src/forge3d/collision/detection.py src/forge3d/sim/world.py src/forge3d/render/realtime/ src/forge3d/facade.py)",
+      "Bash(python -m ruff check src/forge3d/io/ src/forge3d/collision/epa.py src/forge3d/collision/detection.py src/forge3d/sim/world.py src/forge3d/render/realtime/ src/forge3d/facade.py)",
+      "Bash(python -m pytest tests/test_import.py tests/test_backend.py tests/test_math.py tests/test_collision.py tests/test_snapshot.py tests/test_contact_physics.py tests/test_api_usability.py tests/test_realtime_smoke.py tests/test_hq_renderer.py tests/test_conservation.py tests/test_rnea_2dof.py tests/test_crba.py tests/test_aba.py tests/test_p12_friction.py tests/test_p13_rigid_body.py tests/test_robot.py tests/test_mesh_and_io.py -q --tb=short)",
+      "Bash(python -m pytest tests/test_import.py tests/test_snapshot.py tests/test_realtime_smoke.py tests/test_mesh_and_io.py tests/test_collision.py -q --tb=short)",
+      "Bash(python -c \"import forge3d as f3d; print\\('import OK'\\); print\\(f3d.__version__\\); print\\(f3d.__all__\\)\")",
+      "Bash(python -m pytest tests/test_input.py tests/test_camera.py tests/test_app.py -v)",
+      "Bash(python -m pytest tests/ --ignore=tests/test_p9_training.py --ignore=tests/test_p11_jax.py -q)",
+      "Bash(python -m pytest tests/ --ignore=tests/test_p9_training.py --ignore=tests/test_p11_jax.py)",
+      "Bash(ruff check *)",
+      "Bash(ruff format *)",
+      "Bash(mypy src/forge3d/app.py src/forge3d/input.py src/forge3d/camera.py src/forge3d/facade.py src/forge3d/viewer.py src/forge3d/__init__.py --ignore-missing-imports)",
+      "Bash(python3 -)",
+      "Bash(pytest /workspaces/2026_python_toy_project_1/tests/ --ignore=/workspaces/2026_python_toy_project_1/tests/test_p9_training.py -q)",
+      "Bash(git init *)",
+      "Bash(git config *)",
+      "Bash(apt-get install *)",
+      "Bash(git branch *)",
+      "Bash(git -C /workspaces/2026_python_toy_project_1 config user.email \"me@iruki.dev\")",
+      "Bash(git -C /workspaces/2026_python_toy_project_1 config user.name \"forge3d\")",
+      "Bash(git -C /workspaces/2026_python_toy_project_1 branch -m main)",
+      "Bash(GIT_DIR=/workspaces/2026_python_toy_project_1/.git GIT_WORK_TREE=/workspaces/2026_python_toy_project_1 git status)",
+      "Bash(cat)",
+      "Bash(GIT_DIR=/workspaces/2026_python_toy_project_1/.git GIT_WORK_TREE=/workspaces/2026_python_toy_project_1 git branch -m main)",
+      "Bash(pip install *)",
+      "Bash(python -m build)",
+      "Bash(twine check *)",
+      "Bash(python -c \"import forge3d; print\\('forge3d', forge3d.__version__, '✅'\\)\")",
+      "Bash(GIT_DIR=.git GIT_WORK_TREE=. git add .gitignore .readthedocs.yaml .github/ pyproject.toml CHANGELOG.md src/forge3d/__init__.py docs/ README.md CONTRIBUTING.md LICENSE)",
+      "Bash(GIT_DIR=.git GIT_WORK_TREE=. git status --short)",
+      "Bash(GIT_DIR=.git GIT_WORK_TREE=. git add src/ tests/ apps/ assets/ examples/ demos/ validation/ CLAUDE.md)",
+      "Bash(GIT_DIR=.git GIT_WORK_TREE=. git commit -m ' *)",
+      "Bash(mkdocs build *)",
+      "Bash(pytest tests/test_p16_joints.py -v)",
+      "Bash(python -c \"from forge3d.constraints import BallJoint; print\\('OK'\\)\")",
+      "Bash(pytest tests/ --ignore=tests/test_p9_training.py -q)",
+      "Bash(pytest tests/test_import.py -v)",
+      "Bash(pytest tests/ --ignore=tests/test_p9_training.py)",
+      "Bash(mypy src/)",
+      "Bash(pytest tests/test_p17_events.py -v)",
+      "Bash(pytest tests/test_p18_serialization.py -v)",
+      "Bash(pytest tests/test_p19_layers.py -v)",
+      "Bash(pytest tests/test_p20_api.py -v)",
+      "Bash(pytest tests/test_p21_terrain.py -v)",
+      "Bash(pytest tests/test_p23_performance.py -v)",
+      "Bash(python -c \"import forge3d; print\\('forge3d', forge3d.__version__, '✅'\\); print\\('joints:', forge3d.JointHandle.__name__\\); print\\('events:', forge3d.CollisionEvent.__name__\\); print\\('terrain:', forge3d.World.add_terrain.__name__\\)\")",
+      "Bash(GIT_DIR=.git GIT_WORK_TREE=. git add -A)"
+    ],
+    "additionalDirectories": [
+      "/workspaces/2026_python_toy_project_1/src/forge3d"
+    ]
+  }
+}

pyforge3d-1.0.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip --version)",
+      "Bash(python3 -c \"import jax; print\\('jax', jax.__version__\\)\")",
+      "Bash(python3 -c \"import numpy; print\\('numpy', numpy.__version__\\)\")"
+    ]
+  }
+}

pyforge3d-1.0.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*.so
+.eggs/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+logs/
+checkpoints/
+*.mp4
+*.png
+*.states
+*.npz
+site/
+.env
+*.env.local
+*.db
+*.sqlite
+.DS_Store
+Thumbs.db
+*.log
+*.ppm

pyforge3d-1.0.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

pyforge3d-1.0.0/CHANGELOG.md

@@ -0,0 +1,164 @@
+# Changelog
+
+All notable changes to forge3d are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+---
+
+## [1.0.0] — 2026-06-03  ★ STABLE RELEASE
+
+### Added (P15 — MkDocs 문서 사이트)
+- MkDocs Material 테마 기반 문서 사이트 (`mkdocs.yml`, `docs_src/`)
+- API 레퍼런스, 튜토리얼 4종, 아키텍처 개요 페이지
+- ReadTheDocs 설정 (`.readthedocs.yaml`), GitHub Pages 워크플로우
+
+### Added (P16 — 조인트 & 구속 시스템)
+- `forge3d.constraints` 패키지: Sequential Impulse 구속 솔버
+- `FixedJoint`, `BallJoint`, `HingeJoint` (모터·한계 포함), `PrismaticJoint`, `DistanceJoint`, `SpringJoint`
+- `World.add_joint(type, body_a, body_b, ...)` 통합 API; `World.remove_joint(handle)`
+- `forge3d.JointHandle` 핸들 클래스
+
+### Added (P17 — 충돌 이벤트 콜백)
+- `forge3d.CollisionEvent`, `forge3d.CollisionHandler`
+- `World.on_collision_begin`, `on_collision_stay`, `on_collision_end` 데코레이터
+- `World.add_collision_handler(body_a, body_b)` 쌍별 핸들러
+- `World.add_trigger_zone(position, size)` 순수 데이터 존 (물리 충돌 없음)
+- `World.ignore_collision(body_a, body_b)` 쌍별 충돌 무시
+
+### Added (P18 — 씬 직렬화)
+- `World.save(path)` → JSON 저장
+- `World.load(path)` 클래스 메서드 → World 복원
+- `forge3d.StateRecorder` — 프레임별 상태 기록 + npz 저장/재현
+
+### Added (P19 — 충돌 레이어·마스크)
+- `forge3d.CollisionLayer` 비트필드 상수 (`DEFAULT`, `PLAYER`, `ENEMY`, `BULLET` 등)
+- `Body.collision_layer`, `Body.collision_mask` 프로퍼티
+- `World.ignore_collision()` 쌍 기반 물리 충돌 무시 (physics-level)
+
+### Added (P20 — API 강화)
+- `forge3d.errors` 모듈: `Forge3dError`, `ValidationError`, `PhysicsError`, `RenderError`
+- `World()`, `add_box()`, `add_sphere()` 인자 검증 (mass > 0, size > 0, restitution ∈ [0,1])
+- 친절한 에러 메시지 (`ClassName.method() — param must be ... got param=...`)
+
+### Added (P21 — Heightfield 지형)
+- `World.add_terrain(heights, cell_size, origin)` → Heightfield
+- 구 vs 높이맵, 박스 vs 높이맵 충돌 감지 (쌍선형 보간)
+
+### Added (P23 — 아일랜드 슬리핑)
+- 바디 슬리핑 카운터 (`_sleep_counters`)
+- `Body.is_sleeping` 프로퍼티, `PhysicsWorld.wake_body()`
+
+### Changed
+- Version bump: `0.4.0` → `1.0.0` (첫 안정 릴리즈)
+- pyproject.toml `Development Status :: 5 - Production/Stable`
+- Baumgarte 바이어스 부호 수정 (구속 솔버 안정성 대폭 향상)
+
+---
+
+## [0.4.0] — 2026-06-03
+
+### Added (P14 — PyPI 배포 인프라)
+- GitHub Actions CI 워크플로우 (Python 3.12/3.13, push/PR 자동 테스트)
+- GitHub Actions Release 워크플로우 (tag → TestPyPI → PyPI OIDC Trusted Publisher)
+- GitHub Actions Docs 워크플로우 (main 브랜치 → GitHub Pages)
+- `pyproject.toml` 저자·URL 정비 (`authors`, `project.urls`)
+- `[project.optional-dependencies.docs]` — `mkdocs-material`, `mkdocstrings`
+- `[tool.hatch.build.targets.sdist]` exclude 패턴 (테스트·앱·문서 제외)
+- `.readthedocs.yaml` ReadTheDocs 설정
+- `.github/ISSUE_TEMPLATE/` — bug report / feature request 템플릿
+
+### Changed
+- Version bump: `0.3.0` → `0.4.0`
+- `.gitignore` 확장 (`.states`, `.npz`, `site/`, `*.ppm` 등)
+
+### Added
+- `App` class — high-level game-loop abstraction with `@on_start` / `@on_update` / `@on_render` decorators
+- `Input` class — per-frame keyboard/mouse state snapshot (`key_held`, `key_pressed`, `key_released`, `mouse_pos`, `mouse_delta`, `scroll_delta`)
+- `Key` — named key constant class (`Key.SPACE`, `Key.W`, `Key.ESCAPE`, …)
+- `OrbitCamera` — orbit-around-target camera with `rotate()`, `zoom()`, `pan()`, `to_snapshot()`
+- `FollowCamera` — smooth camera that tracks a `Body` from a fixed offset
+- `world.bodies` property — list of all `Body` handles currently in the world
+- `world.remove(body)` — remove a body from the world mid-simulation
+- `world.clear()` — remove all dynamic bodies (keep statics if desired)
+- `world.get_body(name)` — look up a body by name
+- `body.name` — readable name set at creation
+- `body.is_static` — True if the body does not move under physics
+- `body.mass` — body mass in kg
+- `body.apply_force(force)` — accumulate a world-frame force applied during the next `step()`
+- `body.apply_torque(torque)` — accumulate a world-frame torque applied during the next `step()`
+- `body.set_position(pos)` / `body.set_orientation(quat)` — teleport shortcuts
+- `body.set_velocity(vel)` / `body.set_angular_velocity(omega)` — velocity override
+- AABB broad-phase pre-filter in `collision.detection` — O(n²) → O(n log n) contact detection
+- `src/forge3d/py.typed` — PEP 561 type marker (inline types exported)
+- MIT `LICENSE` file
+- `CONTRIBUTING.md` — contribution guide
+
+### Changed
+- `World.__repr__` now includes body count and gravity vector
+- `Body.__repr__` now includes name and velocity magnitude
+- `Viewer` now integrates `Input` state; pass `viewer.input` to access current frame
+- `pyproject.toml` upgraded to full PyPI metadata: classifiers, keywords, URLs, readme, license
+
+### Improved
+- Broad-phase AABB filter reduces GJK calls from O(n²) to only overlapping pairs
+- `world.update_body_pose` uses body-id index cache (O(1) lookup instead of O(n) scan)
+- `world.apply_impulse` likewise O(1) lookup
+- `Viewer.draw()` returns the rendered frame as `ndarray` consistently
+
+---
+
+## [0.2.0] — 2026-05
+
+### Added
+- `Shape.capsule(radius, half_length)` — capsule rigid body
+- `Shape.convex_mesh(mesh_data)` — convex-hull body from OBJ file
+- `world.add_capsule()` / `world.add_mesh()` facade helpers
+- `forge3d.io.load_obj(path)` → `MeshData` — pure-Python OBJ parser
+- `MeshData.hull_vertices` / `.hull_faces` — precomputed convex hull
+- `convex_hull_inertia()` — exact inertia via signed-tetrahedra method
+- GJK extended: support functions for "mesh" and "capsule" shapes
+- EPA (`collision/epa.py`) — penetration depth + contact normal for intersecting convex bodies
+- `gjk_contact()` — public GJK+EPA interface returning `(depth, normal)`
+- PBR shader (Cook-Torrance BRDF): GGX NDF, Smith geometry, Fresnel-Schlick
+- PCF shadow map upgraded to 2 K resolution
+- Reinhard tone mapping + gamma correction
+- Albedo texture support: PNG/JPEG via `imageio`
+- `Material.texture_path` / `.normal_map_path` fields
+- Sample models: `assets/models/cube.obj`, `assets/models/tetrahedron.obj`
+- Capsule VAO cached by `(radius, half_length)` key
+- Mesh VAO cached by `mesh_id`
+
+### Changed
+- Vertex layout: 6 floats → 8 floats `[px, py, pz, nx, ny, nz, u, v]`
+
+---
+
+## [0.1.0] — 2026-03
+
+### Added
+- `World`, `Body`, `Shape`, `Material`, `Viewer`, `Recorder` — public API
+- Rigid-body physics: RNEA, CRBA, ABA; semi-implicit Euler integrator
+- Collision detection: SAT OBB-OBB (15-axis), sphere-sphere, sphere-box,
+  capsule-sphere, capsule-box, capsule-capsule
+- Impulse-based contact solver with Coulomb friction and Baumgarte correction
+- Weld constraints (`world.weld` / `world.release`) for kinematic grasping
+- `world.teleport`, `world.apply_impulse`
+- UR5 6-DOF robot model with forward kinematics and Jacobian
+- `RealtimeRenderer` — OpenGL 3.3 rasteriser via `moderngl` + Xvfb headless
+- `HQRenderer` — software ray-tracer (Blinn-Phong, AO, MSAA)
+- `SceneSnapshot` — pure-data physics↔renderer contract
+- Gymnasium-compatible `ReachEnv` and `PickPlaceEnv`
+- JAX JIT+vmap batch physics (`sim/jax_batch.py`) — 2000× throughput
+- SHAC: analytic policy gradients via FK auto-diff
+- Domain randomisation (`sim/domain_rand.py`)
+- NumPy ↔ JAX backend switch via `ENGINE_BACKEND` env-var
+- 215 automated tests
+
+[Unreleased]: https://github.com/your-org/forge3d/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/your-org/forge3d/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/your-org/forge3d/releases/tag/v0.1.0

pyforge3d-1.0.0/CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md — forge3d
+
+> 매 세션 자동 로딩되는 파일이다. **항상 적용되는 규칙만** 둔다.
+> 가끔만 필요한 절차·도메인 지식은 `docs/`(ROADMAP, SPEC)나 `.claude/skills/`로 옮긴다.
+> 초안은 `/init`로 생성한 뒤 이 형식으로 다듬는다. git에 커밋해 공유한다.
+> `[대괄호]`는 실제 값으로 채운다.
+
+---
+
+## 0. 절대 제약 — YOU MUST (이 프로젝트의 존재 이유)
+
+- **IMPORTANT: 외부 물리엔진(MuJoCo, PyBullet, Bullet, ODE, DART, Isaac, Brax 등)을 엔진 코어에서 사용하지 않는다.** 동역학·접촉·충돌·구속·기구학은 **항상 직접 구현한 코드**가 푼다.
+- 판단 기준 한 줄: **"동역학과 접촉을 누가 푸는가?" → 답은 언제나 우리 코드.** 막혔다고 외부 엔진 호출로 우회하지 않는다. 막히면 멈추고 보고한다.
+- 외부 엔진(`pybullet`, `mujoco`)의 import는 **`validation/` 디렉터리에서 기준값 대조 전용으로만** 허용한다. `src/forge3d/` 안에서는 절대 금지.
+- 써도 되는 패키지: NumPy, JAX, PyTorch, SciPy, SymPy, Gymnasium, optax/flax/equinox, stable-baselines3. (이들은 동역학을 *대신 풀지 않는다*.) **그래픽 출력용** `moderngl`/`pyglet`/`glfw`/`imgui`/`imageio`/`ffmpeg`도 허용 — 단, **물리·접촉 연산에는 절대 쓰지 않는다.**
+- **GPU 제약 해석: "GPU 불가"는 물리·학습 연산 한정이다. 화면에 삼각형을 그리는 그래픽용 OpenGL은 허용**한다(없으면 실시간 렌더링 불가). 단 헤드리스에서 OpenGL 가속 여부가 불확실하면 가정하지 말고 EGL/Xvfb 가능성부터 확인하고 보고한다.
+
+## 0b. 라이브러리 ↔ 응용 분리 — YOU MUST
+
+- 이 프로젝트는 **라이브러리(`src/forge3d/`, 1급 산출물)** 와 **응용(`apps/robot_rl/`)** 의 2층이다. 응용은 라이브러리를 **외부인처럼 import해서만** 쓴다. 응용을 짜려고 라이브러리 내부를 고쳐야 한다면 추상화가 실패한 것이니 멈추고 보고한다.
+- **물리 코어(`math/ dynamics/ collision/ contact/ model/ sim/`)는 렌더러(`render/`)를 import하지 않는다.** 물리↔렌더의 유일한 연결은 `SceneSnapshot`(순수 데이터) 계약뿐이다. 물리 코드가 렌더러나 OpenGL을 알게 하지 않는다.
+- **공개 API는 작게 유지**한다: 처음 만나는 개념 5~6개(`World/Body/Joint/Shape/Viewer/Recorder`) 이내, 진입 예제 15줄 이내, 똑똑한 기본값, z-up·SI 단위. 새 공개 개념을 늘리기 전에 헬퍼·기본값으로 해결되는지 먼저 본다.
+
+## 1. 작업 방식 — 기획안(SPEC) 기반
+
+- **전체 순서의 기준은 `docs/ROADMAP.md`**, 개별 작업의 기준은 `docs/specs/`의 해당 Phase SPEC이다. 이 둘이 source of truth다.
+- 작업 전 해당 SPEC을 읽고, **거기 정의된 범위·파일·완료 조건만** 다룬다. SPEC에 없는 변경은 하지 않는다.
+- **Phase 게이트: 이전 Phase의 검증 기준을 통과하기 전에는 다음 Phase로 넘어가지 않는다.** (ROADMAP의 검증 기준 표 참조)
+- 여러 파일을 건드리거나 접근이 불확실한 작업은 **먼저 plan mode**로 탐색·계획하고, SPEC과 대조해 승인받은 뒤 구현한다.
+- SPEC의 task를 **순서대로, 한 번에 하나씩** 구현한다. task가 끝나면 SPEC 체크박스를 갱신하고 `docs/PROGRESS.md`에 기록한다.
+- **SPEC과 현실이 어긋나면 임의로 우회하지 말고 멈추고 보고한다. 깨진 계획을 땜질하지 않는다.** 필요하면 실패 지점부터 다시 계획한다.
+
+## 2. 엔진 작성 규칙 — 함수형 코어 (np ↔ jnp 호환의 전제)
+
+- **in-place 변형 금지.** 상태는 입력 → 출력으로 전달한다. 배열은 불변으로 다룬다(JAX `arr.at[i].set(v)` 패턴, NumPy도 동일 추상화로 래핑).
+- **난수는 명시적 키로 관리**한다(JAX PRNG 호환). 전역 난수 상태 사용 금지.
+- 분기·루프는 가능하면 벡터화한다. JIT 대상 함수 안에서는 `jax.lax` 제어흐름을 쓴다.
+- **모든 엔진 코드는 `ENGINE_BACKEND=numpy`와 `=jax`에서 동일하게 동작해야 한다.** 한쪽에서만 되는 코드를 작성하지 않는다.
+
+## 3. 백엔드 경계
+
+- **성능 경로(권장)는 all-JAX로 통일**: jnp 엔진 + flax/equinox 정책 + optax + 전체 루프 JIT + `vmap` 다중환경.
+- **torch는 실험·프로토타입(SB3) 전용.**
+- **학습 핫루프에서 JAX 환경 + torch 정책 혼합 금지** (매 스텝 host↔device 동기화로 JIT 이점 소멸). 경계 변환이 꼭 필요하면 DLPack, 단 프로토타이핑에 한함.
+
+## 4. 검증 — YOU MUST
+
+- **"완료/통과/동작함"이라고 말하기 전에 반드시 실제로 실행하고 증거(명령어 + 출력)를 보여준다.** 실행하지 않은 채 통과를 주장하지 않는다.
+- 변경 후 순서: `[pytest]` → `[ruff check]` → `[mypy]`. 셋 다 통과해야 완료.
+- 물리 코드의 정확성 게이트(해당 시 반드시 추가):
+  - **보존 법칙**: 무토크·무감쇠에서 에너지 보존, 외력 없을 때 운동량 보존.
+  - **해석해 대조**: 단진자/이중진자 닫힌 해, RNEA vs 손유도(SymPy).
+  - **기준 엔진 대조**: `validation/`에서 동일 입력을 PyBullet/MuJoCo와 허용오차 내 비교.
+  - **백엔드 일치**: 같은 입력에 대해 np 결과와 jnp 결과가 수치 허용오차 내 일치.
+- 렌더링·API 게이트(해당 시):
+  - **렌더러 계약**: 동일 `SceneSnapshot`이 두 렌더러에서 일관된 장면(실시간=빠른 미리보기, HQ=골든 이미지 비교) — 회귀 테스트.
+  - **API 사용성**: `examples/`의 예제가 *라이브러리 내부를 안 건드리고* 동작(15줄 이내). 이게 추상화가 살아있다는 증거다.
+
+## 5. 명령어 (Claude가 추측할 수 없는 것)
+
+- 백엔드 스위치: `ENGINE_BACKEND=numpy` 또는 `ENGINE_BACKEND=jax` (기본 numpy).
+- 공개 API 스모크: `python -c "import forge3d"` 가 동작해야 한다.
+- 테스트(단일 우선, 성능 위해 전체 스위트 지양): `[pytest tests/test_xxx.py -q]`
+- 린트/포맷: `[ruff check . && ruff format --check .]`
+- 타입: `[mypy src/]`
+- 컨테이너: `[docker compose run --rm dev pytest -q]`
+- CPU 멀티코어: `XLA_FLAGS`, `OMP_NUM_THREADS` 등 스레드 환경변수를 명시적으로 설정.
+
+## 6. 금지 / 사용자 확인 필수
+
+- 확인 없이 금지: 파일·데이터 삭제, `git push --force`, 시크릿/`.env` 커밋, Docker 베이스 이미지 교체.
+- 코드·체크포인트·로그는 **볼륨 마운트**로 컨테이너 밖에 보존한다. 컨테이너 내부에만 남기지 않는다.
+- **물리·학습 연산에 GPU/CUDA 의존성 추가 금지**(이 환경은 CPU 전용). JAX·PyTorch는 CPU 휠만 설치. (그래픽용 OpenGL은 §0의 해석에 따라 허용 — 단 헤드리스 가용성은 확인 후 사용.)
+
+## 7. 저장소 규칙
+
+- 브랜치: `[phase-N/<요약>]` / 커밋: `[type(scope): 요약]` / 한 PR = 한 Phase 또는 그 하위 task 묶음.

pyforge3d-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to forge3d
+
+Thank you for your interest in contributing!
+
+## Quick start
+
+```bash
+git clone https://github.com/your-org/forge3d
+cd forge3d
+pip install -e ".[dev]"
+```
+
+## Workflow
+
+1. Fork the repo and create a feature branch: `git checkout -b feat/my-feature`
+2. Write your changes and corresponding tests
+3. Make sure the checks below pass
+4. Open a PR — one PR per logical change
+
+## Checks (must all pass)
+
+```bash
+ruff check . && ruff format --check .   # lint + format
+mypy src/                               # type checking
+pytest tests/ -q                        # test suite
+```
+
+## Rules
+
+### Physics code
+- Every new formula needs a unit test that checks against an analytical solution,
+  a conservation law (energy / momentum), or a PyBullet/MuJoCo baseline
+  (`validation/` directory).
+- No in-place mutation of arrays. Use `dataclasses.replace(body, vel=new_vel)`.
+- Must run correctly under both `ENGINE_BACKEND=numpy` and `ENGINE_BACKEND=jax`.
+
+### Renderer
+- Physics core (`math/`, `dynamics/`, `collision/`, `contact/`, `model/`, `sim/`)
+  must **never** import renderer code.
+- The only allowed bridge is `SceneSnapshot` (pure data).
+
+### Public API
+- New public concepts require an entry in `__all__` in `src/forge3d/__init__.py`.
+- New public concepts need a usage example in `examples/` (≤ 15 lines).
+
+### Forbidden
+- External physics engines in `src/forge3d/` (MuJoCo, PyBullet, Bullet, etc.).
+  They are allowed only in `validation/` for baseline comparison.
+- GPU/CUDA dependencies for physics or learning code.
+
+## Code style
+
+- [ruff](https://docs.astral.sh/ruff/) for lint and formatting (line length 100).
+- Type annotations on all public functions.
+- Comments only when the *why* is non-obvious.
+- No docstrings for trivial getters / setters.
+
+## Commit style
+
+```
+feat(collision): add sweep-and-prune broad-phase
+fix(contact): clamp Baumgarte correction to avoid tunnelling
+docs(readme): add App-style game loop example
+test(physics): add conservation test for capsule-capsule
+```
+
+## Questions?
+
+Open an issue or start a Discussion on GitHub.

pyforge3d-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 forge3d contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.