Repository navigation
roadmap: chunk rework phases P0–P6 #46
Description
This is the roadmap for the rework decided in #149. Each environment keeps one log, which holds the backend's data and control's state. Gateways, JVMs and the CLI reach core through one sync protocol, chunk.sync.v1. Self-hosted installs and Chunk Cloud share one management API, chunk.management.v1. The rework is split into phases P0 to P6, each with its own issue. Below are each phase's status, what is left, and the open issues that continue alongside the phases. #149 governs where anything here disagrees with it.
Goal
- 5,000 concurrent players in one environment.
- Two launch targets: self-hosting on a single Docker or Podman host, and Chunk Cloud, which runs on a private host provider.
- Both targets use the same environment image, release archive, CLI and management API.
Phases
| Phase | Issue | Scope | Status |
|---|---|---|---|
| P0 | #150 | Review and merge #144 and #145; measure the backend | Done (#144, #145, #159) |
| P1 | #60 | Replicate the log to object storage; restore, retention and forks | Done (#161, #162) |
| P2 | #151 | Control state in the environment log; subscriptions replace polling | Done (#167, #173, #175, #176, #177) |
| P3 | #152 | One environment image; one sync protocol | Done (#181, #182, #185, #186, #187, #219, #231) |
| P4 | #153 | Shared subscriptions, a read pool and backpressure | Done (#162, #165, #166) |
| P5 | #154 | Management API and service, providers, edge, platform CLI | In progress |
| P6 | #155 | Large environments, fleet rollout, a measured 5,000-player run | In progress |
P0 came first. P1 and P2 overlapped, and P3 followed P2. P4 started once P0's measurements existed. P5 ran in parallel, mostly in packages/ and in the private platform repository, and integrated once P3 landed. P6 comes last.
What remains
- P5 (rework P5: management API, providers, edge and platform CLI #154): the chunk side is done: CLI promote, rollback, domains and forks (feat(cli): promote, roll back and manage custom domains #310, feat: fork environments from a snapshot of another's log #311), telemetry (feat(environment): ship a managed core's logs, metrics and usage to management #282), edge readiness (feat(edge): serve readiness on an optional health address #312), management on Drizzle and Bun's S3 client (refactor(management): move to Drizzle ORM on Bun.SQL #314, feat(management): use Bun's S3Client and store releases in an S3-compatible bucket #315), and owner-scoped access and sign-in hooks for installs (feat(management): limit callers to owners, and let installs add sign-in options and routes #316). What's left is in the platform: Cloud sign-in and teams, the Cloud dashboard, and bringing up the edge on Cloud hosts.
- P6 (rework P6: large environments and a measured 5,000-player run #155): several gateways per environment in practice, gateway CPU work, fleet rollout with canaries, measurements on the Cloud hosts, and the 5,000-player run, with results recorded on perf: preserve benchmark evidence and measure integrated operating limits #49.
Continuing alongside the phases
- Toolchain: toolchain: add run and test entry points and bound session startup #56
- Assets: assets: follow-ups after asset revisions (#327) #328 (follow-ups to assets: publish and deliver immutable authorized revisions #58)
- Gameplay and authoring: overworld: deliver optional defaults, map/pack/UI helpers and testing modules #63 (companion modules), design: define gameplay isolates, app/scope authoring and reusable server components #117 (decision record), server: define cross-hook and JVM context readiness handoff #124
- Examples: example: complete the multi-app starter with companion modules and pinned assets #64
chunk dev: cli: list open sessions under nodes in the chunk dev JVM tab #140- Rust cleanup: chore: consolidated Rust cleanup backlog #125
- Benchmark evidence: perf: preserve benchmark evidence and measure integrated operating limits #49
- Gateway protocol: Expose proxy configuration and improve server-list metadata #9, Explore configuration diffing and reuse across server switches #29
- Environment and gateway bugs: environment: a core restored from the log store has no AOT caches #278, chunk-js: URL.parse reentrancy and stack call-site caching can abort the process #300 (two paths left after fix(js): stop application JavaScript from aborting core through URL.parse, stack traces and import() #341)
Closed along the way: #7, #8, #10, #55, #57 (#294, #301, #303), #58 (#327), #59 (#306, #308), #61, #62, #97 (#320), #121, #122, #123, #146, #147, #148, #292 (#340), #299 (#321), #309 (#323, #325), #317 (#326, #331).
Also landed outside the phases: the com.chunkzero.chunk namespace (#329), and an engine-neutral JVM runtime with separate minestom and multistom engines (#334, #335, #336). Chunk no longer converts Anvil worlds; worlds are .polar files (#337).
Process
- New decisions are issues labelled
decision, and each one says what it supersedes. - Review rules for pull requests are in decision: rework chunk around one log per environment and a shared management API #149.
The previous roadmap is in this issue's edit history. It is kept for reference only and no longer describes the plan.
Activity
[-]roadmap: chunk v1 milestones, decisions and knowledgebase index[/-][+]roadmap: chunk rework phases P0–P6[/+]