**Epic / tracking issue.** Introduces a first-class **Package & Plugin system** so functionality (assets, Zig source, native libs, runtime/editor extensions) can be packaged, distributed, and installed into projects without manually copying files — eventually comparable to Unity's Package Manager + Assembly Definition Files + Asset Store, but idiomatic to Zig. This issue tracks the work; implementation lives in the child issues below. --- ## Motivation Reusing functionality between projects today requires manually copying source, assets, and native libraries. There is no manifest, no dependency management, and no path to a marketplace. We want modular development, code isolation, dependency management, and future online-repository/asset-store readiness. ## Terminology (ratified model) | Term | Meaning | Status | |---|---|---| | **OAP** (`.oap`) | The *cooked, runtime* asset container the game ships/streams. Already supports manifests, inter-package deps, DLC/mod overlays. | **Exists** (`editor/AssetPackager.zig`, `open_asset_package` dep) | | **Package** | The *authoring/distribution* unit: a manifest + any mix of assets, Zig source, native libs, plugins. Asset-only / source / native / **hybrid** (the normal case). | **This epic** | | **Module** | A Zig compilation unit (`b.addModule`) — the Unity asmdef equivalent. | Already used per script (`editor/GameCodegen.zig`) | | **Plugin** | The *runtime/editor registration* entry point a Package exposes (registers components/systems/services, or editor panels via #4). | Reuses `engine.Services` + #4 | **OAP is not a competitor to Package** — it's the runtime *output* form. An asset package's assets are cooked into the project `game.oap` at build (or shipped as a prebuilt `.oap` overlay for DLC/mods). ## Key architectural decision **Delegate dependency resolution to Zig's package manager.** `build.zig.zon` + `zig fetch` already give content-addressed hashing, transitive resolution, hash-pinning (the lockfile), and local (`.path`) / remote (`git+https`) deps. Turian's package system is therefore a thin layer on top: a manifest for *engine-integration metadata*, plus build-graph + asset-pipeline injection. The prerequisite is that projects get a real `build.zig.zon` (#57) — today they only have a one-line `project.json` sentinel and the generated game build wires every dependency via hardcoded SDK paths. The "Plugin" runtime/editor extension surface overlaps **#4 (Editor Plugins)** — this epic does **not** rebuild editor menus/panels; it depends on #4 for that and focuses on packaging + runtime registration. --- ## Plan ### MVP — `A → B → C → D + G` Delivers the headline criterion: *install an asset pack from the CLI and it shows up in your build, with no manual copying.* - [ ] #56 — (A) Research & manifest design (`turian-package.json` + ADR) — *foundation, decide the contract first* - [ ] #57 — (B) Project `build.zig.zon` foundation + dependency-resolution refactor — *keystone, highest risk, `t:breaking`* - [ ] #58 — (C) Discovery, manifest parsing & package graph - [ ] #59 — (D) Asset packages (multi-root scan + OAP packaging) — *headline deliverable* - [ ] #60 — (G) CLI commands (install/remove/update/list/info/search) — *pairs with D* ### Postponed / follow-up (tracked, scheduled after MVP) - [ ] #61 — (E) Source packages (modules + reflection + isolation) — *hardest; touches codegen + reflection* - [ ] #62 — (F) Native packages (precompiled lib linking) - [ ] #63 — (H) Studio Package Manager panel — *editor UI; depends on #4 for extension surface* - [ ] #64 — (I) Plugin runtime registration (`engine.Services` entry points) - [ ] #65 — (J) Asset-store / repository API design — *design-first* - [ ] #66 — (K) Authoring documentation — *trails each feature* ## Execution order 1. **#56 (A)** — manifest + ADR (lock the contract). 2. **#57 (B)** — project `build.zig.zon` keystone (do early; everything needs it). 3. **#58 (C)** — discovery / package graph. 4. **#59 (D) + #60 (G)** — asset packages + CLI → **MVP complete**. 5. **#62 (F) → #61 (E)** — native (simpler) then source (reflection-heavy). 6. **#64 (I)** — plugin runtime registration (after E). 7. **#63 (H)** — editor panel (after C+G; ideally after #4). 8. **#65 (J)** — registry design (anytime after A; build later). 9. **#66 (K)** — docs trail each feature. ## Acceptance criteria (epic) - Packages can be installed from the CLI and automatically participate in project builds. - Asset, source, native, and hybrid packages are supported. - Package dependencies are resolved automatically (via Zig's PM). - Projects no longer require manual copying of assets or source. - Package metadata is fully documented. - The Editor provides a Package Manager UI. - The architecture is compatible with a future online package repository. ## Related issues #4 (Editor Plugins — extension surface), #18 (repo splitting — validates multi-package model), #15 (CLI more commands), #7 (dep compile speed), #41 (SOAP services), #6 (Docker SDK distribution).