Document RPG systems roadmap and open design decisions

This commit is contained in:
dingo
2026-09-08 08:33:31 -04:00
parent ece92fa65c
commit be03ca8f25
2 changed files with 384 additions and 1 deletions
+379
View File
@@ -0,0 +1,379 @@
# Aeternalis systems roadmap
Draft for discussion, 2026-09-08. This document organizes requested work; it does
not authorize gameplay implementation or finalize the open decisions below.
Existing behavior is described in `docs/ARCHITECTURE.md` and `docs/PROGRESSION.md`.
Where this draft proposes a change to the current vision, that change remains
pending agreement. Numerical tuning is intentionally left open.
## 1. Direction and existing foundation
Build a survival RPG whose resources, creatures, recipes, spells, abilities, and
events can be authored in Control. Players progress through exploration, use of
skills, experimentation, combat, and surviving worlds.
Already available: character levels and stats, inventory and equipment, permanent
titles with admin exceptions, basic gathering/crafting/melee combat, generated
heightfield terrain, world-ending boss events, and durable survivor passage.
Control already supports item/title authoring, player item/title adjustments,
healing, and some world operations. These are foundations, not the full systems
described here. Existing gathering/crafting/combat XP uses broad categories.
Keep these boundaries throughout implementation:
- Go decides gameplay results; browser/controller inputs express intent.
- One process owns a world. Crossing a chunk boundary stays inside that world.
- Death, inventory ownership, play-time budgets, and survivor passage remain
durable through retries, crashes, and transfers.
- Resurrection is a proposed exception requiring its own agreed lifecycle design.
- Content publishing and live admin actions retain permissions, validation,
version checks, reasons, and audit history.
- Additional features do not imply a higher tested player capacity.
## 2. Shared content and Control
Recommended foundation: separate reusable definitions from instances placed in a
world. A wolf definition describes a kind of creature; an individual spawned wolf
has its own identity, position, health, and state.
| Control editor | What administrators configure |
| --- | --- |
| Assets | Models, equipment attachments, animation sets, sound cues, visual effects |
| Resources | Gathering profession, level requirement, yields, interaction, respawn, model |
| Biomes | Terrain appearance, resource distribution, mob populations, spawn rules |
| Mobs | Stats, level/scaling, behaviors, attacks, model/animations, loot references |
| Loot tables | Weighted/independent rewards, quantities, conditions, nested-table limits |
| Recipes | Profession, ingredients, outputs, requirements, failure and refund rules |
| Effects | Damage, healing, buffs/debuffs, area effects, durations, stacking rules |
| Spells | Acquisition, prerequisites, usage XP, ranks, costs, targeting, effects |
| Abilities | Weapon proficiency and stat requirements, costs, targeting, effects |
| Structures | Build requirements, model/footprint, health, collision, destruction rewards |
| Events | Location, stages, timing, spawns, objectives, announcements, end conditions |
Recommended publishing flow: draft -> validate -> preview/test -> publish version
-> owner applies at a defined safe boundary. Reject missing references, impossible
requirements, circular unlock chains, and unbounded spawn/effect recursion.
Preview final stats and rewards using the same rules as the server.
Start behavior/effect editors with a supported menu of building blocks and
parameters. A new kind of behavior may still need engine work; the editor should
not promise arbitrary gameplay from text or scripts.
Existing acquired equipment and title awards retain their definition snapshots.
Decide explicitly whether other edits affect existing instances, future spawns,
or only newly created worlds. Terrain generation changes especially need versioning
so discovering or reloading a chunk cannot silently replace established geography.
Retire referenced definitions instead of deleting them from saved worlds.
## 3. Gathering and targetable resources
Confirmed profession split:
| Profession | Activity | Progression |
| --- | --- | --- |
| Lumberjack | Wood gathering | Successful wood gathering awards lumberjack XP |
| Herbalist | Herb gathering | Successful herb gathering awards herbalist XP |
| Miner | Ore gathering | Successful mining awards miner XP |
Use **Miner** as the consistent profession name; mining is its activity.
Higher-tier nodes require a higher level in their associated gathering profession.
Profession levels are distinct from overall character level.
Resource definitions should include name, model, profession, required profession
level, output item(s), amount/range, respawn delay/range, and valid biome/spawn
locations. Proposed optional fields: tool requirement, gather duration, number of
successful harvests before depletion, rare yields, and action sounds/animations.
Server checks target existence, range, profession level, tools, and node availability
before awarding items and XP. Depletion and rewards commit together. Respawn state
must survive chunk eviction and restart; unloading a chunk must not replenish it.
Decisions: shared depletion versus per-player nodes; contested harvest ownership;
whether tool tiers gate resources; how luck modifies yields; whether low-tier
resources continue giving full profession XP. Define conversion of existing generic
gathering XP before migration rather than copying it into all three professions.
## 4. Biomes, mobs, and spawning
Biomes connect geography to resource and creature populations. Configure biome
selection rules, terrain/appearance, resource densities, mob pools, and exclusions.
Proposed spawn rules include region/point, biome, elevation/slope, minimum player
distance, population cap, respawn delay, and optional time/world-age conditions.
Choose whether biomes are generated, painted by admins, or a combination.
Mob definitions include base/final stats, level, world-age scaling, model and
animation set, perception, faction/hostility, movement, attack loadout, loot, and
behavior parameters. Initial behavior vocabulary could include idle, wander,
patrol, pursue, attack, flee, return, guard, and swarm toward an objective.
Mobs must cross chunk boundaries while retaining identity, health, threat, and
combat state. Chunks control visibility and local simulation work, not artificial
mob walls. Navigation must account for slopes, obstacles, and player structures.
Decide pursuit/leash limits and what happens when every nearby player leaves.
An event swarm cannot vanish or reset merely because its destination is unloaded.
Loot tables should support quantities, guaranteed rewards, independent chances,
and weighted choices with clear semantics. Determine loot rights, luck application,
and whether rewards are shared or individual. Preserve existing corpse rights
unless a new rule is explicitly agreed. Item creation must not duplicate on retry.
## 5. Crafting and discovery
Confirmed professions: **Weapon Smithing, Armor Making, Jeweler, Carver, Rune Master,
Alchemist, Trap Master, Cook, and Builder**. Each needs its own XP/level track.
Suggested boundaries to confirm: Carver handles wooden components/weapons;
Rune Master handles runes/enchantments; Trap Master handles deployable traps.
Recipe definitions explicitly select their profession rather than inferring it
from the output equipment slot. Multi-profession recipes can be considered later.
Admins author recipes. Players initially do not know them and experiment with
ingredients to discover them. Recommended player loop:
1. Choose a crafting context/station and place ingredient quantities.
2. Submit an attempt; the server matches a hidden recipe and checks requirements.
3. Resolve success or failure, consume ingredients, and award any result atomically.
4. Show the result; optionally record a successful discovery in a personal journal.
Recipe data: ingredient identities/quantities, output(s), profession, level/stat
requirements if applicable, station/tools, duration, XP reward, and failure rules.
Decide exact ingredient matching versus tags/substitutions, order sensitivity,
batching, and whether experimentation offers hints.
Confirmed: higher crafting proficiency makes failure less costly in materials.
Separate **no matching recipe**, **requirements unmet**, and **a valid craft that
fails a success roll**. These may need different costs and feedback; random failure
of valid recipes is not yet a confirmed requirement.
Proposed failure policy: select the relevant profession before the attempt, apply
a bounded loss rate that decreases with proficiency, and show the maximum material
loss before submission. Agree per-item rounding and any minimum loss, especially
for a single rare ingredient. Preserve exact equipment instance identity if it is
returned. Invalid packets or stale inventories should not count as experiments.
Keep undiscovered recipe ingredients/results out of public APIs and client bundles;
the browser sends offered ingredients rather than the ID of a secret recipe.
Discovery can prevent direct data extraction but cannot prevent players sharing
recipes externally. Decide whether knowledge belongs to a character or account,
whether known recipes become repeatable shortcuts, and whether failed attempts
give bounded XP. Repeated impossible attempts must not become free XP generation.
## 6. Terrain, movement, presentation, and controls
Requested: greater terrain depth, closer default camera, jumping, animated players
and mobs, action sound effects, a simple character creator, and visible equipment.
Recommended first terrain scope: more pronounced hills, valleys, slopes, and terrain
landmarks using the existing heightfield. Caves, overhangs, and stacked walkable
floors are a separate scope decision because a heightfield cannot represent them.
Agree this before navigation, jumping, and structure placement are finalized.
Jumping needs server-owned vertical velocity, grounded state, collisions, and landing
rules. Decide stamina cost, fall damage, air control, and combat while airborne.
Camera defaults should support adjustable distance and avoid terrain/structure
clipping. Camera presentation does not change server targeting rules.
Create an asset contract before expanding the model library: scale, orientation,
skeleton, animation names, attachment sockets, collision shape, and asset budgets.
The initial creator can offer a bounded set of body/face/hair/color presets pending
agreement. Visual choices should not silently change hitboxes or stats.
Equipment uses the existing slots for appearance, with attachment/replacement meshes,
compatible rigs, and a policy for hidden slots and layering. Decide whether every
ring/earring needs visible geometry. Animation states should cover locomotion,
jump, gathering, crafting, attacks/casting, reactions, and death.
Sound cues attach to actions and outcomes, with distance attenuation, category
volume controls, and limits on simultaneous playback. Predicted animations/sounds
must reconcile with authoritative outcomes without playing every event twice.
Input actions should be independent of physical buttons: WASD/joystick movement,
jump, interact, targeting, and configurable ability/spell slots. Support keyboard
and controller rebinding, saved profiles, conflict feedback, controller dead zones,
and usable menus. Decide mouse aim versus lock-on/directional controller targeting,
hold/toggle behavior, and the hotbar size. Bindings never bypass server validation.
## 7. Combat, effects, spells, and weapon abilities
Agree a shared combat contract before authoring many attacks. It should cover melee,
ranged weapons, projectiles, self/target/ground aiming, line of sight, range, hit
validation, attack timing, resource costs, cooldowns, interruption, and death.
Decide physical projectiles versus instant hits for ranged weapons, ammunition,
shield/block rules, damage types/resistances, friendly fire, and targeting assistance.
Recommended common effect system: direct damage/healing, timed buffs/debuffs,
damage/healing over time, control effects, and area effects. Area definitions need
shape/radius, valid targets, duration, tick interval, stacking/refresh policy,
source attribution, and target/work limits. Distinguish a moving aura from a fixed
ground area and a one-time burst. Effects and projectiles must resolve across chunk
borders; visibility boundaries must not clip damage or healing.
Spells and abilities should reuse this effect system, including mob attacks and
admin events. Present stat/effect calculations clearly in Control; define whether
values are sampled at cast time or recalculated on each tick.
### Spells
- Books can be dropped, found, or rewarded and teach spells.
- A newly learned spell starts at **spell level 1**; this does not imply that every
character can learn every spell at character level 1.
- Individual spells gain XP through use and can unlock other spells at specified
ranks. Control authors the unlock graph, requirements, progression, and effects.
- Configure mana/other costs, cooldown, cast/channel time, range, targeting, and
rank scaling. Define where knowledge and spell points are spent, if anywhere.
- Decide whether books are consumed, whether duplicate books are usable/tradable,
whether learning is automatic or chosen, and whether unlocks need another book.
- Define meaningful usage for XP: avoid free progression from healing full-health
targets, hitting nothing, or multiplying rewards by every aura tick/target.
### Weapon abilities
Weapon-type proficiency XP and stat requirements jointly unlock abilities. Control
authors weapon categories, thresholds, additional prerequisites, costs, and effects.
Decide XP credit for hits versus kills/useful combat, offhand/shared credit, whether
abilities remain usable after a weapon swap, and whether temporary stat bonuses
can satisfy learning or activation requirements. Keep unlock rules distinct from
activation rules. Legacy generic combat XP needs an agreed migration policy.
### Resurrection: unresolved lifecycle change
Requested constraints: the caster must be next to the corpse, and the dead player's
account must not have created a replacement character. This interprets "amount"
in the request as "account." Healing a living player is separate from resurrection.
The current rule makes death immediately permanent. Two designs to choose between:
1. **Recoverable death window:** a new intermediate corpse state can be resurrected;
expiry or choosing a replacement life finalizes permanent death. This would add
a new lifecycle state, while keeping finalized deaths irreversible.
2. **Explicit resurrection of a recorded death:** eligible death records can return
to life under strict rules. This changes the existing terminal-death invariant
and requires an explicitly approved replacement specification.
Recommendation for discussion: a short, clearly communicated recoverable window.
Do not implement either option until the rule is agreed. Decide time limit, cost,
spell requirements, cast interruption, consent/offline targets, restored health,
repeat resurrection limits, and corpse access/looting behavior.
In either design, account replacement creation and resurrection must compete in
one atomic ownership decision. Only one can succeed, including simultaneous casts
or requests arriving in different worlds. Already-looted items cannot be recreated.
Resurrection must not reset daily usage, duplicate passage, or revive a character
inside a collapsed world. Define how world victory/collapse and daily cap interact
with recoverable corpses before changing code.
## 8. Building, housing, hub, and later social systems
Builder creates walls, forts, camps, and other structures. All structures persist
in their world across unloads, disconnects, and restarts; players and mobs can
destroy them. Configure construction recipes/costs, footprint and placement rules,
health, collision/navigation impact, damage rules, and destruction results.
Agree ownership/access, construction time, repair, limits, decay if any, and
restrictions near spawns, safe zones, corpses, and critical routes. Persistence
across world collapse is unresolved; it is not implied by persistence in a world.
Housing is a later layer: player storage and invitations need ownership, guest
permissions, secure container transfers, and a decision on instanced interiors
versus buildings in the open world. If houses can be destroyed, decide the fate
of stored items and offline occupants. A safe/indestructible house would be an
explicit exception to the requested universal structure-destruction rule.
The survivor hub is exploratory. Confirm eligibility, whether it is a permanent
world, safety/PvP, daily-time accounting, storage/housing, and routes back into new
survival worlds. Entry must preserve character identity and inventory and redeem
passage only once. A hub cannot silently permit cloning or unrestricted world hops.
Also decide whether it consumes a slot in the planned five-world infrastructure.
Deferred: player communication, direct trade, parties, guilds, and dungeons. Keep
them visible in planning without requiring their full implementation now. Chat
needs channels and moderation; trade needs atomic item exchange; parties/guilds
need membership, invitations, shared targeting/loot rules; dungeons need entry,
ownership/instancing, reset, death, rewards, and exit/transfer rules. Decide which
relationships persist across death and between worlds.
## 9. Live administration and events
Requested operator tools:
| Action | Parameters and expected behavior |
| --- | --- |
| Spawn mobs | Definition, count, world, position/region; validate placement and population limits |
| Create/run events | Authored stages, triggers/timing, location, objectives, rewards, completion/failure |
| Swarm an area | Select existing mobs or spawn a wave, destination, count, duration, behavior after arrival |
| Global messages | Message and explicit audience: current world or all worlds; persistent delivery identity |
| Delay Harbinger | Preview current/new arrival time and apply a bounded explicit schedule change |
| Heal players | Living target(s), amount/full heal and range of recipients; existing single-player healing is a foundation |
Add event inspection, stop/cancel, and clear cleanup policy for event-spawned mobs,
temporary effects, and rewards already earned. Persist event progress, timers, and
reward claims so a restart cannot repeat a wave or pay the same reward twice.
Swarm movement uses normal cross-chunk navigation and must respect a bounded AI
budget. Decide whether swarms can enter protected areas.
Separate content authoring from live execution permissions. Commands should preview
scope/count, require a reason, carry a request ID, and report pending/completed/
rejected results. Repeated delivery cannot spawn duplicate mobs or repeat rewards.
Delaying the Harbinger before arrival is distinct from pausing an already active
collapse. Define which is allowed, extension limits, affected countdowns, and
player announcements. Never restore a lost world through a timing edit. Admin
healing does not revive dead characters or reset their daily allowance. Announcements
are an in-game feature proposal; no external messages are sent by this plan.
## 10. Proposed implementation sequence
Each phase should produce one playable, reviewable slice before expanding its
content library. These are dependency-based phases, not time or capacity estimates.
| Phase | Deliverable | Exit criteria |
| --- | --- | --- |
| 0. Agree rules | Resolve the decisions below; define progression and content schemas | Examples for success, failure, death, and transfer are agreed |
| 1. Authoring foundation | Versioned definitions, asset references, reusable requirements/effects, previews | Bad references/edits rejected; existing saves load unchanged |
| 2. World and gathering | Initial biome, resource editor, three gathering professions, terrain/camera/jump baseline | Higher-tier node gates correctly; rewards/respawn survive reload; movement matches terrain |
| 3. Combat and creatures | Melee/ranged contract, navigation, mob/spawn/loot editors, animated test combat | Mobs/projectiles/AoE work across chunks; no duplicate loot; measured crowded encounter |
| 4. Crafting and building | Hidden recipes, nine professions, failure losses, first persistent destructible structures | Trial/success/failure conserve items; structures survive restart and update navigation |
| 5. Spells and abilities | Spell books/ranks/unlocks, weapon proficiency, effects, rebinding/controller support | Use-to-progress and targeting work; unlock cycles and XP exploits covered |
| 6. Live operations | Spawn/swarm/event tools, announcements, Harbinger scheduling, expanded healing | Audited retry-safe commands; event resumes/cancels correctly after restart |
| 7. Presentation completion | Simple creator, broader animation/sound library, visible gear and camera polish | Equipment/rig compatibility and keyboard/controller UI checked |
| 8. Survivor expansion | Agreed hub slice, then separately scoped trade/social/dungeons/housing | Transfers/storage/permissions preserve ownership and daily time |
Asset conventions and basic action bindings begin in phase 1, even though their
full player-facing scope lands later. Phase 2 terrain choices must inform phase 3
navigation. Phase 3 provides structure-aware navigation hooks; phase 4 completes
them with real buildings. Phase 3 tests AoE using simple effects before the full
spell progression UI exists. Phase 6 depends on the mob/effect foundation and can
move ahead of phases 4/5 if live admin tools are the higher priority.
Resurrection gets a separate implementation gate after lifecycle rules are approved;
it is not bundled into ordinary healing or silently included in phase 5.
## 11. Decisions to resolve together
First discussion, because these affect the architecture:
1. Resurrection: recoverable window or explicit reversal; which costs/time limits?
2. Terrain: hills/valleys first, or caves/overhangs/stacked spaces from the outset?
3. Combat: action aiming model, controller targeting, friendly fire, ranged projectiles?
4. Progression ownership: professions, discoveries, spells, and weapon XP belong to
the character or account? Recommendation: character progression survives passage
but resets on replacement; account-level recipe knowledge remains a separate choice.
5. Crafting: exact matching, stations, discovery journal, and whether valid recipes
can randomly fail? What loss applies to an unknown combination?
6. World permanence: what happens to structures/storage at collapse, and what role
does the hub play? Resolve the destruction rule for future houses.
Before each related phase: tool tiers and node sharing; profession/weapon XP curves;
mob aggression/leash and loot rights; spell-point/skill-point purpose; aura stacking
and XP credit; structure permissions; live event limits; Harbinger extension policy;
creator scope and asset sourcing. Keep these open rather than inventing final tuning.
## 12. Validation and completion policy
For each implemented slice run the repository checks (`npm run check`, `npm run
build`, and `go test ./...` in `server`), plus focused browser and lifecycle tests
appropriate to the changes. Generate protocol bindings through `npm run generate`.
Test progression, consumption/rewards, restart, retries, death, daily cap, and
survivor transfer together. Use representative load scenarios for dense mobs,
projectiles, areas, structures, and animations before changing capacity claims.
This draft changes documentation only. No new game rules, assets, admin commands,
schema migrations, or deployment settings are implemented by writing it.
+5 -1
View File
@@ -106,4 +106,8 @@ Tracked across:
- Networking: is node size (128x128x128) fixed/final, or a placeholder for tuning?
## Backlog
- More pillars pending — user indicated there's a lot more to come in follow-up messages.
- See [Systems roadmap](SYSTEMS-ROADMAP.md) for the September 8 draft covering
gathering professions, biomes, mobs, crafting, terrain, combat, spells, abilities,
structures, survivor hubs, presentation, social systems, and live administration.
Its recommendations and unresolved lifecycle changes remain pending discussion;
it does not replace the confirmed rules above.