epic(meta): Kotlin DSL for Adventure (→ 1.0)

[LMLiam]

Outcome

Deliver Kotventure 1.0 as a complete multiplatform Kotlin domain-specific language (DSL) for Adventure.

Kotventure supports Paper, Velocity, and Fabric. It combines a broad Adventure DSL with typed MiniMessage templates, component-test tools, message catalogue tooling, and explicit platform integration.

Product intent

Kotventure makes correct Adventure use direct and testable.

• Wrap Adventure instead of reimplementing it.
• Keep core dependent only on adventure-api.
• Use small optional modules for MiniMessage, serialisers, coroutines, platforms, testing, and tooling.
• Prefer compile-time contracts. Use explicit registries only when runtime lookup is required.
• Keep each issue and pull request as one coherent vertical result.

Phase gates

1. Alpha: Complete the planned public surface while compatibility can still change. Keep tests and documentation current.
2. Beta: Complete build(api): define and enforce Kotventure API stability #55. Verify supported Adventure, Paper, Velocity, Fabric, Java, and publication boundaries through test(compat): verify Adventure and Paper support boundaries #324, bug(build): publish and verify module-specific Java compatibility #372, and build(publish): complete and consume the published module set #413.
3. Release: Complete the integration, publication, documentation, and release-readiness outcomes. Publish and verify version 1.0.0 through chore(build): release 1.0.0 #63.

The phase milestones and native sub-issues show current progress. They are the live work list.

Sources of truth

• Design owns the product architecture and module boundaries.
• Roadmap owns lifecycle stages and phase gates.
• Native sub-issues, dependencies, milestones, and the roadmap project show current work state.
• docs(meta): reconcile roadmap and epic status #390 owns manual semantic reconciliation between the roadmap and this epic.
• refactor(meta): centralise module facts and enforce architecture boundaries #378 can supply mechanical module facts. It does not decide product scope or phase state.

Completion

Keep this epic open through the 1.0.0 release.

Close it only when:

• all retained 1.0 outcomes are complete or explicitly not planned;
• the supported module set is published and consumed from an isolated repository;
• the compatibility and API-stability gates pass;
• release documentation and migration guidance are complete; and
• chore(build): release 1.0.0 #63 verifies the 1.0.0 release and recovery procedure.

Operating rules

• Do not copy detailed child scope into this body.
• Do not use this body as a daily work list.
• Use native blockers only for real prerequisites.
• Use epic(meta): coordinate repository audit remediation #403 for repository-audit remediation. Do not mix that programme into this product epic.

[LMLiam]

@coderabbitai is anything missing from this epic, and that we should create more sub-issues for?

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch the issue details
gh issue view 5 --repo LMLiam/KyoriAdventureDSL --json title,body,labels,comments

# Also list all existing issues to see what sub-issues already exist
gh issue list --repo LMLiam/KyoriAdventureDSL --state all --json number,title,body,labels,state

Length of output: 38474

---

---

@LMLiam The epic is extremely well scoped — the phasing and granularity are both solid. Here are the gaps I'd consider turning into sub-issues, roughly ordered by impact:

---

🔴 High impact — clear gaps in planned scope

1. feat(audience): add the resource pack DSL (Phase 2)
Adventure 4.x ships a rich resource pack API (ResourcePackRequest, callbacks for accept/decline/download progress, Audience.clearResourcePacks()). This is part of the full audience surface promised by the epic but is completely absent. A DSL like:

audience.sendResourcePack {
    url("https://...")
    hash("...")
    required(true)
    onDecline { ... }
}

2. test(test): add a mock/recording audience for audience DSL testing (Phase 2, alongside #31)
The test module has component matchers (#31) and snapshot testing (#32), but there's no utility for asserting audience interactions — e.g., "was a title sent?", "was this sound played?". A RecordingAudience / MockAudience that captures calls is the standard pattern and would make testing Phases 2–3 far easier. This is arguably as important as the component matchers.

3. feat(paper): add Folia scheduler support (Phase 2 or 4)
Issue #42 mentions "scheduler bridges Bukkit/Folia scheduling" in a single line, but Folia's regionized threading is fundamentally different — it requires region-aware task dispatch and cannot be bolted onto the Bukkit scheduler. Given the project targets Paper (which ships Folia), this warrants its own issue.

---

🟡 Medium impact — breadth/polish gaps

4. docs(velocity): add a sample Velocity plugin + docs(fabric): add a sample Fabric plugin (Phase 5)
Issue #61 is Paper-only. Since Velocity and Fabric are first-class platforms in the epic, they should each have a sample/smoke plugin too.

5. feat(i18n): add adventure-extra-kotlin migration guide (Phase 5, alongside #62)
Issue #62 covers migration from adventure-kt, but adventure-extra-kotlin (the official Kotlin extras, widely used) is a separate library with its own surface. Users migrating from it need a distinct guide — different APIs, different artefact IDs.

6. feat(core): add component utility extensions (compact, visitor, reduce) (Phase 1)
No issue covers Component.compact(), deep visitor/fold helpers, or normalization utilities. These are regularly needed when working with large trees (optimisation for #56, round-trip testing, etc.) and fit naturally in Phase 1 with the serializer extensions (#30).

---

🟢 Lower priority / nice-to-have

7. chore(build): introduce a Gradle version catalog (.toml) (Phase 0 or 1)
Standard practice for multi-module Kotlin/Gradle projects. Currently no issue tracks this.

8. ci(build): add code-coverage gate (Phase 1 or 4)
Issue #11 sets up basic CI (build/test/format). No issue adds a coverage report or threshold (JaCoCo/Kover), which would be consistent with "correctness tooling" as a differentiator.

9. feat(audience): add the sign editor DSL (Phase 2 or 4)
Audience.openSignEditor() is platform-level Adventure (Paper). Niche, but if the goal is full breadth of the audience surface, it's the one remaining item from Paper's Adventure API not covered.

---

Summary table

#	Title	Phase	Priority
–	feat(audience): add the resource pack DSL	2	🔴 High
–	test(test): add a mock/recording audience	2	🔴 High
–	feat(paper): add Folia scheduler support	2/4	🔴 High
–	docs(velocity/fabric): add sample plugins	5	🟡 Medium
–	feat(i18n): adventure-extra-kotlin migration guide	5	🟡 Medium
–	feat(core): component utility extensions	1	🟡 Medium
–	chore(build): Gradle version catalog	0/1	🟢 Low
–	ci(build): add code-coverage gate	1/4	🟢 Low
–	feat(audience): sign editor DSL	2/4	🟢 Low

Would you like me to go ahead and create any of these as GitHub issues (with full acceptance criteria, dependencies, and milestone assignments matching the existing style)?

[LMLiam]

Added the CodeRabbit gap-pass follow-ups as roadmap sub-issues and folded them into this epic checklist:

• feat(audience): add the resource pack DSL #65 — feat(audience): add the resource pack DSL
• test(test): add a recording audience and interaction-test toolkit #66 — test(test): add a mock/recording audience for audience DSL testing
• feat(paper): add Folia scheduler support #67 — feat(paper): add Folia scheduler support
• docs(velocity): add a sample Velocity plugin #68 — docs(velocity): add a sample Velocity plugin
• docs(fabric): add a sample Fabric mod #69 — docs(fabric): add a sample Fabric plugin
• docs(docs): add adventure-extra-kotlin migration guide #70 — docs(docs): add adventure-extra-kotlin migration guide
• feat(core): add component utility extensions #71 — feat(core): add component utility extensions
• chore(build): introduce a Gradle version catalog #72 — chore(build): introduce a Gradle version catalog
• ci(build): add a code coverage gate #73 — ci(build): add a code coverage gate
• feat(paper): add the sign editor DSL #74 — feat(audience): add the sign editor DSL

Notes:

• Split the combined Velocity/Fabric sample-plugin suggestion into two issues so each platform remains an independently shippable slice.
• Kept the migration guide as docs(docs) rather than feat(i18n) to match the repo's existing migration-guide issue style (docs(docs): finalise the README and adventure-kt migration guide #62).