skills-and-advancement

Skills and Advancement Skill

You are helping work with the Oxidus skill and advancement systems. Follow the lpc-coding-style skill for all LPC formatting.

Architecture Overview

skills.lpc (std/living/skills.lpc)           — nested skill tree, use-based improvement
advancement.lpc (std/living/advancement.lpc) — per-living XP/level state
advance.lpc (adm/daemons/advance.lpc)        — TNL formula, kill_xp, earn_xp
attributes.lpc (std/living/attributes.lpc)   — STR/DEX/CON/INT/WIS/CHA
boon.lpc (std/living/boon.lpc)               — buff/debuff modifiers on skills and vitals

All of these are inherited by STD_BODY and apply to both players and NPCs.

Skill System — std/living/skills.lpc

Storage Structure

Skills are a nested tree, not a flat mapping:

skills = ([
    "combat": ([
        "level": 3.47,
        "subskills": ([
            "melee": ([
                "level": 2.15,
                "subskills": ([
                    "slashing": ([ "level": 4.82, "subskills": ([]) ]),
                    "piercing": ([ "level": 1.03, "subskills": ([]) ]),
                    "bludgeoning": ([ "level": 2.60, "subskills": ([]) ]),
                    "unarmed": ([ "level": 1.55, "subskills": ([]) ]),
                ]),
            ]),
            "defence": ([
                "level": 1.90,
                "subskills": ([
                    "dodge": ([ "level": 3.21, "subskills": ([]) ]),
                    "parry": ([ "level": 1.10, "subskills": ([]) ]),
                ]),
            ]),
        ]),
    ]),
])

Dot notation addresses nodes: "combat.melee.slashing" navigates the tree.

The integer part of the level is the effective skill level. The fractional part is progress toward the next level (0-99%).

A private find_skill_node(string skill) helper walks the dot-path and returns the live node mapping (or 0). Every read/leaf-mutate function delegates to it — add_skill and remove_skill keep their own walks because they need creation / parent-ref semantics.

Default Skill Tree (from config)

The tree lives under SKILLS.learnable in adm/etc/default.lpml:

combat
  defence: dodge, parry
  melee: attack, bludgeoning, piercing, slashing, unarmed
social: barter, charm, intimidate, persuade
general: appraise, hide, jump, listen, search, spot, swim

Full dot-path examples: "combat.melee.slashing", "combat.defence.dodge", "social.barter", "general.swim".

"combat.defence.evade" is used by combat but is not in the learnable tree — it is created on first use by assure_skill().

Improvement Tuning Knobs (config)

The rest of the SKILLS block holds the numbers use_skill reads on every call:

COMBAT.NPC_SKILL_MULTIPLIER is the matching knob for NPC skill levels.

Read the current values from adm/etc/default.lpml, and never restate them in code, comments, or a call site. They are tuning knobs and they move; a literal copied out of that file is wrong the next time it is turned. Everything below describes the shape of the maths, not the numbers going into it.

Key Functions

Use-Based Improvement

Players improve skills transparently by using them — no skill points or manual allocation.

use_skill() is the only entry point. An unknown skill is created instead of rolled, so the first use costs a call:

varargs int use_skill(string skill, mixed improvement) {
    // unknown skill -> assure_skill() at 1.0, no roll this call
    // known skill   -> roll, then pick a node, clamp, improve
}

The chance is not flat. It is improve_chance.floor + dim_hyperbolic(raw, improve_chance.ceiling), where dim_hyperbolic(v, s) == (s * v) / (s + v). That starts at the floor, reaches floor + ceiling/2 when the raw skill equals the ceiling, and approaches floor + ceiling asymptotically — higher skill means a more frequent roll, and the cap is what slows advancement down.

use_skill() is called throughout the codebase:

• Combat: attacker trains weapon skill after each swing, defender trains defence skill on every hit attempt.
• Any system can call use_skill("general.swim") etc. to trigger organic improvement.

improvement replaces the SKILLS.default_gain bound for this call. It is a bound, not an award — improve_skill applies random_float() of it.

Omit it unless the call site genuinely wants to advance at a different rate from everything else, and if you do pass one, read SKILLS.default_gain before choosing the literal — the argument is an absolute bound, not a multiplier, so whether a given number speeds a call site up or slows it down depends entirely on where the default currently sits. Existing spell and ability sites pass literals (victim->use_skill("combat.defence.evade", 0.1);) that were chosen against an older default.

Improvement Algorithm

Selection and application are separate functions. use_skill() orchestrates:

1. Roll. random_float(100.0) < improve_chance.floor + dim_hyperbolic(raw, improve_chance.ceiling). Fail -> return 0.
2. Select — determine_skill_to_improve(skill, query_level() * cap_factor):
   • Candidates are the skill itself and every ancestor: "combat.melee.slashing" -> ({ "combat", "combat.melee", "combat.melee.slashing" }).
   • Any candidate whose query_raw_skill() is at or over the cap is dropped.
   • Survivors are weighted (segments + 1) * 3 and drawn with element_of_weighted(). For a full 3-segment path: leaf 12, middle 9, root 6 — 44% / 33% / 22%. As parents cap out, the surviving weights redistribute toward the leaf.
   • All capped -> undefined, and use_skill returns 0 even though the roll succeeded.
3. Clamp — clamp_improvement(chosen, improvement) trims the bound to cap - current, so a near-cap node gets a proportionally smaller bound.
4. Apply — improve_skill(chosen, clamped) coerces the bound to a float (float as-is, int promoted, functional evaluated against this_object(), omitted -> SKILLS.default_gain via ??=), adds random_float(bound) to that node, and notifies the player if the floored level rose.

This means using "combat.melee.slashing" can also improve "combat.melee" or "combat" — but with lower probability. Parent skills grow organically as their children are used, but more slowly because they are picked less often.

The cap is query_level() * SKILLS.cap_factor — base level, not query_effective_level(), so a level boon does not raise the ceiling. Progress rolls freely over intervening level boundaries; only the cap halts it, and the only way to lift it is to level.

Query API Grid

Four query functions form an orthogonal grid over two axes: floored vs raw flo

Content truncated.