Epic: Plugin & Package System

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 (closed)). Reuses engine.Services + #4 (closed)

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 (closed)) — 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 (closed) (Editor Plugins) — this epic does not rebuild editor menus/panels; it depends on #4 (closed) 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 (closed) — (A) Research & manifest design (turian-package.json + ADR) — foundation, decide the contract first
  • #57 (closed) — (B) Project build.zig.zon foundation + dependency-resolution refactor — keystone, highest risk, t:breaking
  • #58 (closed) — (C) Discovery, manifest parsing & package graph
  • #59 (closed) — (D) Asset packages (multi-root scan + OAP packaging) — headline deliverable
  • #60 (closed) — (G) CLI commands (install/remove/update/list/info/search) — pairs with D

Postponed / follow-up (tracked, scheduled after MVP)

  • #61 (closed) — (E) Source packages (modules + reflection + isolation) — hardest; touches codegen + reflection
  • #62 (closed) — (F) Native packages (precompiled lib linking)
  • #63 — (H) Studio Package Manager panel — editor UI; depends on #4 (closed) 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 (closed) (A) — manifest + ADR (lock the contract).
  2. #57 (closed) (B) — project build.zig.zon keystone (do early; everything needs it).
  3. #58 (closed) (C) — discovery / package graph.
  4. #59 (closed) (D) + #60 (closed) (G) — asset packages + CLI → MVP complete.
  5. #62 (closed) (F) → #61 (closed) (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 (closed)).
  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 (closed) (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).

Edited by Bruno Massa