Independent project · Active
Matcha! Suite
Thirteen modular server products covering competition, progression, delivery, commerce, player movement, and live systems. Briar designed, built, documented, and released the suite.
Supporting recordOpen the project recordRole, runtime, scale, and the public product surface
- My role
- Product design, systems, code, interface, identity, documentation, tools, and releases
- Runtime
- Server-side JVM modules · exact dependencies vary by product
- Project scale
- 13 live modules · hundreds of documentation pages · 19 browser authoring tools
- Web platform
- Product site · documentation · authoring tools · services · dashboard · release infrastructure
Competition · progression · delivery · commerce · movement · live systems
Product site · documentation · services · dashboard · release infrastructure
About this case study. The diagrams condense documented implementations and behaviour into a readable overview. Links beside each selected system open the corresponding documentation. Planned and concept-stage modules are not included in the live-module count.
Overview · The suite
Thirteen products, one suite.
Each product owns one server responsibility and has its own installation path. Shared services appear where coordination is necessary, but operators do not have to deploy the suite as one application.
- 01Module boundaries follow server responsibilities, not pages in one shared user interface.
- 02Ceremony supplies selected shared persistence and service components; requirements are declared per install guide.
- 03MongoDB and Redis appear only where durable or distributed state requires them.
- 04Configuration, permissions, diagnostics, and recovery are part of every product.
Supporting recordOpen the suite registerEvery live module, its responsibility, and implemented surface
| ID | Module | Owned responsibility | Implemented surface |
|---|---|---|---|
| 01 | Frontier | Ranked battle system | Queues, formats, ratings, arenas, seasons, tournaments, replays |
| 02 | Journey | Quest and progression runtime | Tasks, parties, zones, flags, timelines, encounters, scripts |
| 03 | Courier | Mail and reward delivery | Messages, durable packages, offline delivery, claim recovery |
| 04 | Bazaar | Distributed item market | Listings, auctions, buy orders, collections, browser market |
| 05 | Link Cable | Cross-server player state | Ownership, six state lanes, handoff, backups, restore |
| 06 | Smart Trainers | NPC battle AI | Reusable move, switch, item, doubles, and gimmick policies |
| 07 | Bloom | Targeted spawn lures | Placed area effects for type, species, form, shiny, and ability odds |
| 08 | Outbreaks | Timed spawn events | Configured pools, alerts, distance, progress, limits, rewards |
| 09 | Venture | Creature jobs | Eligibility, timed work, persisted assignment, result and return |
| 10 | Alchemy | Item migration | Data-driven conditions, transformations, preservation, cleanup |
| 11 | Wonder | Queued WonderTrade | Channels, eligibility, matching, fallback pools, delayed claims |
| 12 | ShowdownActions | Custom battle effects | Data-defined forms, buffs, status, weather, and terrain |
| 13 | MoLang Extensions | Expanded scripting | Functions, conditionals, loops, structs, and imports |
Selected system · Link Cable
Distributed session ownership and handoff.
Link Cable runs on every application backend while the proxy remains unmodified. One backend coordinates guarded handoffs; the others participate through shared Redis and MongoDB services.
Working reconstruction · Ownership handoff
Move one owner without permitting two writers.
Step through the implemented handoff, then introduce the failures the source actually guards: an owner changing during capture, a stale cache, a post-write mismatch, or a late write from the old backend.
- CAPTURECapture changed lanesACTIVE / A / E41
- VERIFYRe-check ownershipepoch 41 required
- PERSISTWrite + verify snapshotcanonical + cache / v89
- HANDOFFPublish handoff recordSNAPSHOT_WRITTEN
- CLAIMDestination prepares loadLOADING / B / E42
- ACTIVATEApply lanes + activateACTIVE / B / E42
Supporting recordInspect ownership and recoveryNetwork authority, state lanes, invariants, and guarded failure paths
- 01Capture all six state groups as one checksummed snapshot
- 02Re-check the source backend, ACTIVE state, and owner epoch
- 03Persist canonical storage and hot cache; read back and verify
- 04Offer a versioned handoff in SNAPSHOT_WRITTEN state
- 05Claim on the target, move to LOADING, and advance the epoch
- 06Apply the matching snapshot and activate the new owner
Player core includes inventory, ender chest, hunger, XP, abilities, recipe book, and supported attached component data.
Ownership invariants
- Writer
- Only the backend holding the current ownership epoch may write live state.
- Concurrency
- Transfers for one player serialize behind the same distributed lock.
- Persistence
- MongoDB is canonical; Redis holds short-lived coordination and handoff data.
- Liveness
- Backend heartbeats let the network identify an owner that has disappeared.
Recovery paths
- Backup unit
- One backup contains all six synchronized lanes.
- Restore gate
- The player must be offline before an operator can restore state.
- Overwrite guard
- A new backup is taken before an existing state is replaced.
- Crash exposure
- Periodic flushing bounds the window between live state and canonical storage.
| Observed condition | Risk | System response | Operator surface |
|---|---|---|---|
| Duplicate transfer request | Two writers race | Per-player lock serializes the requests | Busy / retry signal |
| Stale source resumes | Old state overwrites new | Owner-epoch fencing rejects the stale writer | Safety log |
| Orchestrator unavailable | Authority cannot settle handoff | In-flight transfers retry and stall; participants already hosting players remain live | Role and heartbeat status |
| Stale hot cache | Target loads an older version | Claim version mismatch sends the target to canonical storage instead | Version and load-source telemetry |
| Manual restoration | Overwrite live player data | Offline-only restore with a pre-overwrite backup | Explicit admin command |
Selected system · Journey
Visual authoring and content execution.
Journey separates authored content from runtime machinery. The V3 editor turns task dependencies into MoLang requirements, while the runtime handles tasks, zones, flags, timelines, groups, and encounters.
Working reconstruction · Journey editor V3
Wire the prerequisite. Inspect what ships.
These are the editor's real task objects and modes. Connect one task to another, then inspect the MoLang requirement compiled into the exported task definition.
Signal survey
signal_survey- 01Locate the origin
locate_origin - 02Record the pattern
record_pattern
Archive entry
archive_entry- 01Decode the signal
decode_signal - 02File the report
file_report
Field notes
field_notes- 01Compare the marks
compare_marks - 02Trace the route
trace_route - 03Test a theory
test_theory
Working reconstruction · Blockly generator
Assemble the blocks. Read the exact output.
The production authoring tool turns typed blocks into MoLang text. This reduced bench keeps that boundary: no invented evaluator, test context, or pretend runtime.
Player queries4
- Player has flag
- Player completed task
- Player completed subtask
- Player level
Logic4
- AND
- OR
- NOT
- Boolean
Actions6
- Tell player message
- Execute command
- Start task
- Add / remove flag
- Give / remove item
- Launch timeline
Control flow5
- If / then / else
- For each
- Repeat
- Return
- Break / continue
Variables7
- Set variable
- Get variable
- Query variable
- Temp variable
- Context variable
- Entity variable
- Array access
Math4
- Compare
- Math operation
- Math function
- Number
Text1
- Text string
Supporting recordInspect the authoring runtimeExecution path, exported task shape, authoring objects, and public references
{
"name": "archive_entry",
"display_name": "Archive entry",
"sequential": "SEQUENTIAL",
"start_requirement":
"q.player.has_completed_task('journey:signal_survey')",
"subtasks": [{
"id": "decode_signal",
"event": "INTERACTION",
"filter": "1.0",
"target": 1
}],
"rewards": []
}Reduced from the editor's exported task definition. The incoming graph edge supplies the start requirement.
Declarative path
JSON task and content files cover repeatable progression without requiring a new compiled module for each questline.
Imperative path
Scripts subscribe to game events and execute bounded custom behaviour when the data model is not enough.
Iteration path
Hot reload, in-game editors, generated references, and browser authoring tools shorten the path from authoring to testing.
Selected system · Bazaar
In-game, domain, and browser transaction surfaces.
Bazaar exposes the same market through the game, a domain and persistence layer, and an optional browser dashboard. Authentication begins in game; market and player events return over HTTP and WebSocket.
Working reconstruction · Event projections
Move the market. Watch every read model follow.
Commands append domain events; projectors update listings and each player's collection. Freeze the market, trigger the anti-snipe window, or redeliver a settlement to test its real guards.
Gilded field kit
Anonymous seller · quantity 1
- Current bid
- 1,200
- Bidder
- Rook
- Bids
- 1
- Expires in
- 01:20
No unclaimed entries.
Supporting recordInspect the market surfacesBrowser routes, transaction flow, event contract, controls, and public references
A component map of the implemented routes, filters, charts, and client behaviour. No production market data is shown.
- 01Validate player, channel, asset, limits, and price controls
- 02Append the listing event to the durable stream
- 03Expose the same listing in game and over the API
- 04Settle purchase, bid, expiry, cancellation, or buy-order fill
- 05Collect resulting assets through player-scoped durable entries
- 06Publish market and player events to subscribed clients
Projected web events
{ type: "listing.bid", listingId, bidderId, amount }Cross-server mode
- Topology
- Local or orchestrator / participant roles, with Redis connecting nodes.
- Compatibility
- Every participating node must run the same Bazaar version.
- Degraded state
- Read-only behaviour preserves inspection while writes cannot be trusted.
Operator controls
- Freeze
- Stop market mutation without removing its history.
- Reconcile
- Inspect and repair differences between expected and persisted market state.
- Security
- Configured limits, detectors, permission gates, alerts, and audit-facing inspection.
Selected system · Frontier
Queue search and live-match state.
Frontier validates queue entry, searches with two independently expanding rating windows, allocates a finite arena, and carries the resulting match through countdown, preview, active play, conclusion, and cleanup.
Working reconstruction · Queue manager
A match only exists when both windows overlap.
Each queued player gets a separate search expansion: ten rating points per second, capped at five hundred. The queue accepts the pair only when the rating distance fits inside both windows.
A's window admits B, but B's window is still 40 points short.
- Order
- A considered first · longest waiting
- Same-IP gate
- Clear
- Result multiplier
- 1.0 · first meeting
Supporting recordInspect the queue and match recordState machine, design decisions, configuration surfaces, and public reference
Snapshot rating on entry
The queue compares players against the state they entered with, not a value that can drift invisibly during the wait.
Require mutual overlap
Each player's window expands at its own rate. A wide window on one side cannot force the other player into a match.
Reserve queue membership early
The queue marks a player before asynchronous rating loading, preventing a second join from racing the first.
Allocate world capacity
Arenas are finite resources with positions, restrictions, return behaviour, and cross-server ownership.
Bound the live match
Turn timing, disconnect handling, observation, and recovery prevent a competitive match from becoming indefinite.
Keep match history
Result history and in-world replay let players revisit a battle after it has finished.
What I made · Process · Outcome
From product code to public release.
Alongside the modules, Matcha includes the material needed to configure, inspect, update, and recover the software. The project is published through working releases, authoring tools, documentation, and operator controls.
Documentation & tools
Astro 5 · Starlight · React 19 · TypeScript · Radix UI · Tailwind
Visual authoring
Blockly · React Flow · Three.js · Mermaid · JSZip
Backend & commerce
Fastify 5 · TypeScript 5.8 · Drizzle ORM · SQLite · Discord.js · Stripe · web push
Operations
React + Vite admin dashboard · Cloudflare Worker · read-only TypeScript MCP server
Supporting recordInspect implementation and releaseDeliverables, maintenance loop, verification, and operator surface
Product code
Server modules, selected shared Ceremony services, persistence models, command and permission surfaces.
Authoring formats
HOCON, JSON, datapacks, GUI definitions, tooltips, themes, scripts, and module-specific schemas.
Browser tools
19 public authoring and inspection tools in the documentation site snapshot.
Documentation
Hundreds of public pages covering installation, configuration, concepts, reference, examples, rollout, and recovery.
Releases
Per-module files, compatibility notes, dependencies, version history, and release portal entries.
Validation
Input checks, permissions, dry paths, health signals, staff inspection, backups, restore, and migration guidance.
Public links