diff --git a/planning/SYSTEMS-ROADMAP.md b/planning/SYSTEMS-ROADMAP.md new file mode 100644 index 0000000..a89df05 --- /dev/null +++ b/planning/SYSTEMS-ROADMAP.md @@ -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. diff --git a/planning/VISION.md b/planning/VISION.md index 2c7b5b8..8efd33f 100644 --- a/planning/VISION.md +++ b/planning/VISION.md @@ -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.