{"id":49888057,"url":"https://github.com/kingkyylian/realitykitpipelineguide","last_synced_at":"2026-05-15T19:06:40.916Z","repository":{"id":355276443,"uuid":"1227461586","full_name":"kingkyylian/realitykitpipelineguide","owner":"kingkyylian","description":"A teaching repo for the full Blender → USDZ → RealityKit iOS game asset pipeline","archived":false,"fork":false,"pushed_at":"2026-05-10T16:44:07.000Z","size":3002,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-10T18:30:30.792Z","etag":null,"topics":["asset-pipeline","blender","game-development","ios","realitykit","swift","usdz","xcode"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kingkyylian.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-02T18:04:47.000Z","updated_at":"2026-05-10T16:42:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kingkyylian/realitykitpipelineguide","commit_stats":null,"previous_names":["kingkyylian/realitykitpipelineguide"],"tags_count":1,"template":true,"template_full_name":null,"purl":"pkg:github/kingkyylian/realitykitpipelineguide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingkyylian%2Frealitykitpipelineguide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingkyylian%2Frealitykitpipelineguide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingkyylian%2Frealitykitpipelineguide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingkyylian%2Frealitykitpipelineguide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kingkyylian","download_url":"https://codeload.github.com/kingkyylian/realitykitpipelineguide/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingkyylian%2Frealitykitpipelineguide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33075302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asset-pipeline","blender","game-development","ios","realitykit","swift","usdz","xcode"],"created_at":"2026-05-15T19:06:28.939Z","updated_at":"2026-05-15T19:06:40.904Z","avatar_url":"https://github.com/kingkyylian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RealityKit Pipeline Toolkit\n\n[![CI](https://github.com/kingkyylian/realitykitpipelineguide/actions/workflows/ci.yml/badge.svg)](https://github.com/kingkyylian/realitykitpipelineguide/actions/workflows/ci.yml)\n![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python\u0026logoColor=white)\n![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)\n![RealityKit](https://img.shields.io/badge/RealityKit-iOS%20fixture-black?logo=apple\u0026logoColor=white)\n\nA command-first RealityKit asset pipeline toolkit for taking a gameplay asset from brief to Blender/USDZ output, RealityKit verification, simulator evidence, and release checks.\n\n`rkp` is the product. The included SwiftUI + RealityKit target-shooting app is a verification fixture used to prove that generated or imported assets actually load in RealityKit. `rkg` is experimental labs work on top of the same pipeline; it is not the main user path.\n\nMost RealityKit tutorials stop at code. This repo treats asset production as part of the game loop: each Blender/USDZ asset has a manifest entry, mobile budget, loader contract, screenshot, and learning note.\n\n![RealityKit pipeline gameplay demo](Docs/screenshots/demo.gif)\n\n## What This Is\n\nPrimary product:\n\n- `rkp`: the installable CLI for asset status, validation, scaffolding, Blender builds, USDZ inspection, screenshot-based acceptance, tests, and release checks.\n- `Skills/realitykit-pipeline-guide`: an installable Codex skill that points agents at the same asset, build, and documentation contracts.\n- `.claude/commands`: slash commands such as `/rkp`, `/rkp-asset`, and `/rkp-status` for agent-style usage.\n- `Sources/RealityKitPipelineDemo`: a small playable RealityKit verification fixture that proves pipeline output inside an iOS app.\n- `Docs`: the teaching, production, and AI-agent handoff layer around the same pipeline.\n\nExperimental labs:\n\n- `rkg`: a game-factory research CLI for scoring ideas, validating specs, scaffolding small RealityKit projects, and generating QA/store-pack docs. Treat it as active research on top of RKP, not as a finished commercial game generator.\n\nGenerated assets are tool outputs first. Keep them in `Assets/Imported` and copy or load them in your own RealityKit game when needed; the fixture app is only a verification harness and does not automatically switch its default gameplay target to every newly generated asset.\n\n## Product Boundary\n\n| Surface | Maturity | Use it for | Do not assume |\n| --- | --- | --- | --- |\n| `rkp` asset pipeline | Preview, actively usable | Asset contracts, Blender/USDZ drafts, manifest health, screenshot acceptance, and release gates. | Fully automatic text-to-3D, automatic Xcode project edits, or asset acceptance without screenshot evidence. |\n| RealityKit fixture app | Verification harness | Proving imported USDZ files load and behave inside RealityKit. | A production game architecture or the default destination for every generated asset. |\n| Codex skill and docs | Teaching/handoff layer | Keeping agents and contributors on the same commands, contracts, and verification gates. | A standalone MCP server; JSON CLI output is the current automation surface. |\n| `rkg` game factory | Experimental labs | GameSpec validation, small generated project scaffolds, archetype exploration, QA/store-pack planning. | A finished commercial game factory or automated App Store submission system. |\n\n## The Normal RKP Path\n\n```bash\nrkp init --project-name MyGame\nrkp make-asset enemy_drone --type gameplay_target --prompt \"red bullseye drone target\"\nrkp inspect-usdz enemy_drone\nrkp verify-asset enemy_drone --build\nrkp release-check\n```\n\nWhen simulator or device evidence is available, accept the asset:\n\n```bash\nrkp accept-asset enemy_drone --screenshot Docs/screenshots/enemy_drone_imported.jpg\n```\n\nThis is the product loop. Everything else in the repository exists to teach, verify, or extend that loop.\n\n## Quick Start\n\nPrerequisites:\n\n- Python 3.10+ and `pipx`.\n- Blender 4.x if you want to build generated Blender assets locally. See `Docs/blender-support.md` for the support and fallback matrix.\n- macOS with Xcode and XcodeGen only if you want to run the included iOS verification fixture.\n\nInstall the CLI directly from GitHub:\n\n```bash\npipx install git+https://github.com/kingkyylian/realitykitpipelineguide.git\nrkp --version\n```\n\nBootstrap any RealityKit project from that project's root:\n\n```bash\nrkp init --project-name MyGame\nrkp doctor\nrkp make-asset enemy_drone --type gameplay_target --prompt \"red bullseye drone target\"\nrkp release-check\n```\n\nMachine-readable status and doctor output are available for scripts and agents:\n\n```bash\nrkp status --json\nrkp doctor --json\nrkp doctor --blender --json\n```\n\nThe detailed command manual is `Docs/cli-tool.md`.\n\n## Asset Acceptance\n\nRKP keeps draft generation separate from production acceptance:\n\n1. `make-asset` writes the manifest entry, asset brief, and generator script.\n2. `build-asset` creates a USDZ draft through Blender or, when requested, the direct fallback builder.\n3. `inspect-usdz` checks package presence, texture budget, UV signal, and known triangle budget.\n4. `accept-asset` records screenshot evidence and moves the manifest status to `imported`.\n5. `release-check` validates the repo or external project gate.\n\nFallback builds are still drafts. `rkp build-asset enemy_drone --fallback-only` deliberately skips Blender and uses the direct USDZ fallback path when `usdzip` is available, but it does not remove the screenshot acceptance requirement.\n\n## Verification Fixture\n\n| Textured target scoring | Imported arena floor |\n| --- | --- |\n| ![Ring scoring inner hit](Docs/screenshots/ring_scoring_inner_hit.jpg) | ![Imported arena floor](Docs/screenshots/arena_floor_imported.jpg) |\n\nThe fixture app starts with procedural RealityKit fallbacks so it can compile before any custom art exists. The asset pipeline then replaces placeholders with USDZ files exported from Blender into `Assets/Imported`.\n\nTo build the included fixture locally:\n\n```bash\nmake bootstrap-dev\nmake verify-local\n.venv/bin/python Tools/rkp.py release-check\n```\n\nCoreSimulator warnings can appear in sandboxed environments; the gate is accepted only when the command exits `0` and prints `release-check ok`.\n\n## Documentation Map\n\n- `Docs/cli-tool.md`: normal RKP commands, JSON automation, advanced backends, and `v0.1` limits.\n- `Docs/blender-support.md`: Blender version expectations, `usdzip` fallback behavior, and setup diagnostics.\n- `Docs/guide.md`: teaching guide for the full asset journey from gameplay need to RealityKit evidence.\n- `Docs/pdf/realitykit-pipeline-guide.pdf`: shareable PDF snapshot of the guide.\n- `Docs/production-playbook.md`: production feature/asset gates and definition of done.\n- `Docs/new-game-startup.md`: checklist for starting a future RealityKit game.\n- `Docs/slash-commands.md`: slash command usage for agent CLIs.\n- `Docs/first-good-issues.md`: learner-sized issue candidates.\n- `Docs/github-showcase.md`: repo description, topics, and release copy.\n- `Docs/ai-handoff.md`: fast orientation page for AI agents and future sessions.\n- `Docs/WORKLOG.md`: sprint history, decisions, command evidence, and learning notes.\n\n## What You Learn\n\n- Build a SwiftUI + RealityKit verification fixture.\n- Generate and import Blender-authored USDZ assets.\n- Keep asset scale, origin, UVs, materials, and texture budgets under control.\n- Connect visual texture design to gameplay with ring-based scoring.\n- Verify every asset with CLI checks, builds, screenshots, and worklog notes.\n\nCurrent completed learning modules include first USDZ import, scale/orientation tuning, base color texture, UV `st` primvar lessons, ring-based scoring, arena floor fallback/import, a strong guide PDF, and an installable `rkp` CLI surface.\n\n## Known Limits In v0.1\n\n- RKP generates asset contracts, Blender scripts, USDZ drafts, manifest status, and release checks; it does not automatically wire arbitrary Xcode project resources.\n- Blender background USDZ export is machine-sensitive. Use `rkp doctor --blender` for diagnostics and `rkp build-asset --fallback-only` when direct USDZ draft output is intentional.\n- The fallback builder is for prompt-backed procedural drafts. Visual acceptance still requires loading the USDZ in RealityKit and providing screenshot evidence.\n- RKG is experimental. It can scaffold and verify small fixed-camera RealityKit projects, but generated games still need human product review, visual QA, screenshots, and App Store preparation.\n- No standalone MCP server ships yet. `rkp status --json` and `rkp doctor --json` are the stable machine-readable surfaces.\n- The package version is currently `0.2.1`. Pin GitHub installs to a tag for reproducible tool behavior.\n\n## GitHub Metadata\n\nSuggested repo description:\n\n```text\nCommand-first Blender -\u003e USDZ -\u003e RealityKit asset pipeline toolkit with CLI, Codex skill, slash commands, and an iOS verification fixture.\n```\n\nSuggested topics:\n\n```text\nrealitykit, swift, swiftui, ios, blender, usdz, codex-skill, developer-tools, 3d-pipeline, asset-pipeline\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingkyylian%2Frealitykitpipelineguide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkingkyylian%2Frealitykitpipelineguide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingkyylian%2Frealitykitpipelineguide/lists"}