@xforge-dev/forge-kit 0.23.0 → 0.24.0

package/README.md

@@ -129,6 +129,15 @@ example `2026-10-29T18:30:00Z`). CI fails a content change that keeps the old st
 check a board with (`boardProblem`). A preset places characters by `legionNameKey(name)`, the md5 of
 the lowercased name without spaces, so a stored board never holds names.
 
+### Legion Points (GMS v.272)
+
+v.272 removes the board. The points model sits beside it (the board stays for app versions still reading it):
+`legionPoints` (the automatic raid's ranks, B 1 … SSS 5, as many members as the Legion rank holds), stat levels
+(`LegionStats`, one point a level, `statCap` 15 for basic stats and up to 40 for expanded ones by Legion level),
+`allocationProblem`, `statTotals`, `suggestStats`, the two highest event blocks (`appliedEventBlocks`), 10 named
+presets (`SharedPoints`, stored under `points` in the shared row so an older board write leaves it alone) and the 5th
+Champion slot (`championSlotsOpen`). Values not yet confirmed sit in one marked block in `src/legion.ts`.
+
 ## Exports
 
 `isForgeAuthConfigured` is exported from the root and `/client` entry points.

package/dist/legion.d.ts

@@ -164,3 +164,110 @@ export declare function blocksFrom(raw: unknown): EventBlock[];
 export declare function sharedBoardFrom(raw: unknown): SharedBoard | null;
 /** Valid crystals: nine at most, levels 0–5, up to 3 known lines each, a line on at most 2 crystals. */
 export declare function crystalsFrom(raw: unknown): ArtifactCrystal[];
+/** The Legion's 16 stats, keyed as the grid's areas were. */
+export type LegionStatKey = GridKey;
+/** Basic stats, open from the start (the patch notes' order). */
+export declare const BASIC_STATS: readonly ["str", "dex", "int", "luk", "att", "matt", "hp", "mp"];
+/** Expanded stats, opening together at Legion level 2,000 (the patch notes' order). */
+export declare const EXPANDED_STATS: readonly ["critDamage", "boss", "ied", "critRate", "buffDuration", "normal", "exp", "statusResist"];
+export type ExpandedStat = (typeof EXPANDED_STATS)[number];
+export declare const LEGION_STATS: readonly GridKey[];
+export declare const STAT_LABELS: Record<GridKey, string>;
+/** Legion Points a member gives by rank (patch notes): B 1, A 2, S 3, SS 4, SSS 5. */
+export declare const RANK_POINTS: Record<LegionRank, number>;
+export declare const STAT_PRESETS = 10;
+export declare const PRESET_NAME_MAX = 20;
+export declare const defaultPresetName: (i: number) => string;
+/** Legion ranks by Legion level: name, the level it starts at, its raid members (the wiki's table) and insignia. */
+export type LegionLevelRank = {
+    name: string;
+    minLevel: number;
+    members: number;
+    image: string;
+};
+export declare const LEGION_LEVEL_RANKS: readonly LegionLevelRank[];
+/** The Legion rank at this Legion level, or null below Nameless I (500). */
+export declare function legionLevelRank(level: number): LegionLevelRank | null;
+/** Members the automatic Legion Raid takes at this Legion level (Nameless I's 9 below it). */
+export declare const raidMembers: (level: number) => number;
+/** Each stat's highest level. */
+export declare const STAT_MAX_LEVEL: Record<GridKey, number>;
+/** The expanded stats' shared level cap by Legion level (the guide's 유니온 레벨별 확장 스탯 최대 레벨). */
+export declare const EXPANDED_CAPS: readonly {
+    level: number;
+    cap: number;
+}[];
+/** The expanded stats' level cap at this Legion level: 0 below 2,000. */
+export declare function expandedCap(legionLevel: number): number;
+/** What one level of each stat gives. */
+export declare const STAT_PER_LEVEL: Record<GridKey, number>;
+/** Points an applied event block gives. */
+export declare const eventBlockPoints: (_b: EventBlock) => number;
+/** Stat levels, one per point: absent or 0 when nothing is spent. */
+export type LegionStats = Partial<Record<GridKey, number>>;
+export declare const isExpandedStat: (k: GridKey) => k is ExpandedStat;
+/** A stat's level cap at this Legion level: basic stats 15, expanded stats as the Legion level allows. */
+export declare const statCap: (k: GridKey, legionLevel: number) => number;
+/** Whether a stat is open at this Legion level. */
+export declare const statUnlocked: (k: GridKey, legionLevel: number) => boolean;
+/** One member as the points model reads it: `rank` null below B (no points, no effect). */
+export type PointsMember = {
+    level: number;
+    rank: LegionRank | null;
+};
+/**
+ * The members the automatic raid takes: the highest levels with a rank, as many as the Legion level's rank holds.
+ * The caller works out ranks (Zero's own levels) and Legion level.
+ */
+export declare function raidComposition<M extends PointsMember>(members: readonly M[], legionLevel: number): M[];
+/** The two event blocks that apply: the highest values among those owned. */
+export declare function appliedEventBlocks(owned: readonly EventBlock[]): EventBlock[];
+/** Legion Points to spend: the raid's ranks (and the applied event blocks', none as far as known). */
+export declare function legionPoints(members: readonly PointsMember[], legionLevel: number, owned?: readonly EventBlock[]): number;
+/** Points the stat levels spend. */
+export declare const pointsSpent: (stats: LegionStats) => number;
+/** What each stat gives at its level (only stats with a level). */
+export declare function statTotals(stats: LegionStats): LegionStats;
+/** What's wrong with an allocation, or null: no stat past its cap at the Legion level, no overspending. */
+export declare function allocationProblem(a: {
+    stats: LegionStats;
+    points: number;
+    legionLevel: number;
+}): string | null;
+/**
+ * The best allocation for linear weights (value per stat level, e.g. damage per level): with every level costing one
+ * point, the open stats fill highest weight first, each to its cap. Stats without a positive weight get nothing.
+ */
+export declare function suggestStats(weights: Partial<Record<GridKey, number>>, points: number, legionLevel: number): LegionStats;
+/** Valid stat levels: known stats, whole numbers within each stat's cap, zeros dropped. */
+export declare function statsFrom(raw: unknown): LegionStats;
+/** Valid owned event blocks: known blocks at one of their values, each within its copies. */
+export declare function ownedBlocksFrom(raw: unknown): EventBlock[];
+/** A Legion Stat Preset: its name and stat levels. */
+export type StatPreset = {
+    name: string;
+    stats: LegionStats;
+};
+/**
+ * The points part of a world's Legion, stored under `points` in the shared row so an older app's board write (which
+ * merges `presets`, `active` and `crystals`) leaves it alone: 10 presets, the one in use (0-based) and the event
+ * blocks owned.
+ */
+export type SharedPoints = {
+    presets: StatPreset[];
+    active: number;
+    blocks: EventBlock[];
+};
+export declare const emptyStatPreset: (i: number) => StatPreset;
+export declare const emptySharedPoints: () => SharedPoints;
+/** A preset name trimmed to PRESET_NAME_MAX, or the default for its slot when blank. */
+export declare function presetName(raw: unknown, i: number): string;
+/** A stored points part as a valid one: always 10 presets, missing ones empty. Anything else (absent, older rows) is empty. */
+export declare function sharedPointsFrom(raw: unknown): SharedPoints;
+/** Whether a stored world Legion has the points part (a row written by an app that knows v.272). */
+export declare const hasPoints: (legion: unknown) => boolean;
+/** Legion Champion slots: 4, and a 5th once four Champions are rank S or higher. */
+export declare const CHAMPION_SLOTS = 5;
+export declare const CHAMPION_FIFTH_SLOT_RANK: LegionRank;
+/** Open Champion slots for the Champions' ranks (C, B … SSS; anything below B counts as none). */
+export declare function championSlotsOpen(ranks: readonly string[]): number;

package/dist/legion.js

@@ -195,3 +195,185 @@ export function crystalsFrom(raw) {
         return { level, lines };
     });
 }
+/** Basic stats, open from the start (the patch notes' order). */
+export const BASIC_STATS = ['str', 'dex', 'int', 'luk', 'att', 'matt', 'hp', 'mp'];
+/** Expanded stats, opening together at Legion level 2,000 (the patch notes' order). */
+export const EXPANDED_STATS = [
+    'critDamage', 'boss', 'ied', 'critRate', 'buffDuration', 'normal', 'exp', 'statusResist',
+];
+export const LEGION_STATS = [...BASIC_STATS, ...EXPANDED_STATS];
+export const STAT_LABELS = { ...GRID_LABELS, att: 'Attack Power', ied: 'Ignore Defense', normal: 'Normal Enemy Damage', exp: 'EXP Obtained' };
+/** Legion Points a member gives by rank (patch notes): B 1, A 2, S 3, SS 4, SSS 5. */
+export const RANK_POINTS = { B: 1, A: 2, S: 3, SS: 4, SSS: 5 };
+export const STAT_PRESETS = 10;
+export const PRESET_NAME_MAX = 20;
+export const defaultPresetName = (i) => `Preset ${i + 1}`;
+const RANK_TIERS = [['Nameless', 9], ['Renowned', 18], ['Heroic', 27], ['Legendary', 36], ['Supreme', 41]];
+const ROMAN = ['I', 'II', 'III', 'IV', 'V'];
+export const LEGION_LEVEL_RANKS = RANK_TIERS.flatMap(([tier, first], t) => ROMAN.map((roman, r) => ({
+    name: `${tier} Legion Rank ${roman}`,
+    minLevel: 500 * (5 * t + r + 1),
+    members: first + r,
+    image: `${CDN}/legion/ranks/${tier}_Legion_Rank_${r + 1}.png`,
+})));
+/** The Legion rank at this Legion level, or null below Nameless I (500). */
+export function legionLevelRank(level) {
+    let out = null;
+    for (const r of LEGION_LEVEL_RANKS)
+        if (level >= r.minLevel)
+            out = r;
+    return out;
+}
+/** Members the automatic Legion Raid takes at this Legion level (Nameless I's 9 below it). */
+export const raidMembers = (level) => (legionLevelRank(level) ?? LEGION_LEVEL_RANKS[0]).members;
+// Confirmed from KMS 1.2.416 (the same revamp, 2026-06-18; maplestory.nexon.com News/Update/806 and the official game
+// guide, Guide/N23GameInformation/Articles/407): basic stats go to level 15, expanded stats to 40; the 8 expanded stats
+// open together, their cap rising with Legion level (below); points are only the raid's ranks (a KMST screenshot:
+// Supreme I, 41 members, 202 points).
+/** Each stat's highest level. */
+export const STAT_MAX_LEVEL = Object.fromEntries(GRID_KEYS.map((k) => [k, gridMax(k)]));
+/** The expanded stats' shared level cap by Legion level (the guide's 유니온 레벨별 확장 스탯 최대 레벨). */
+export const EXPANDED_CAPS = [
+    { level: 2000, cap: 5 }, { level: 3000, cap: 10 }, { level: 4000, cap: 20 }, { level: 5000, cap: 30 }, { level: 6000, cap: 40 },
+];
+/** The expanded stats' level cap at this Legion level: 0 below 2,000. */
+export function expandedCap(legionLevel) {
+    let cap = 0;
+    for (const c of EXPANDED_CAPS)
+        if (legionLevel >= c.level)
+            cap = c.cap;
+    return cap;
+}
+// ┌─ ASSUMED VALUES ────────────────────────────────────────────────────────────────────────────────────────────────┐
+// │ Not in the v.272 notes nor any KMS source found: what a stat level gives. Each is taken as one old grid square    │
+// │ (KMS says the stats are "the same types as the old occupation effects", and the caps and 440 total match the      │
+// │ board). Nor whether event blocks give points: taken as none (the notes only say they apply automatically and      │
+// │ don't count as members). Change them here only; everything below reads them.                                      │
+// └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+/** What one level of each stat gives. */
+export const STAT_PER_LEVEL = { ...GRID_PER_SQUARE };
+/** Points an applied event block gives. */
+export const eventBlockPoints = (_b) => 0;
+export const isExpandedStat = (k) => EXPANDED_STATS.includes(k);
+/** A stat's level cap at this Legion level: basic stats 15, expanded stats as the Legion level allows. */
+export const statCap = (k, legionLevel) => (isExpandedStat(k) ? Math.min(expandedCap(legionLevel), STAT_MAX_LEVEL[k]) : STAT_MAX_LEVEL[k]);
+/** Whether a stat is open at this Legion level. */
+export const statUnlocked = (k, legionLevel) => statCap(k, legionLevel) > 0;
+/**
+ * The members the automatic raid takes: the highest levels with a rank, as many as the Legion level's rank holds.
+ * The caller works out ranks (Zero's own levels) and Legion level.
+ */
+export function raidComposition(members, legionLevel) {
+    return members.filter((m) => m.rank).sort((a, b) => b.level - a.level).slice(0, raidMembers(legionLevel));
+}
+/** The two event blocks that apply: the highest values among those owned. */
+export function appliedEventBlocks(owned) {
+    return [...owned].sort((a, b) => b.value - a.value).slice(0, MAX_EVENT_BLOCKS);
+}
+/** Legion Points to spend: the raid's ranks (and the applied event blocks', none as far as known). */
+export function legionPoints(members, legionLevel, owned = []) {
+    return raidComposition(members, legionLevel).reduce((t, m) => t + RANK_POINTS[m.rank], 0)
+        + appliedEventBlocks(owned).reduce((t, b) => t + eventBlockPoints(b), 0);
+}
+/** Points the stat levels spend. */
+export const pointsSpent = (stats) => Object.values(stats).reduce((t, n) => t + (n ?? 0), 0);
+/** What each stat gives at its level (only stats with a level). */
+export function statTotals(stats) {
+    const out = {};
+    for (const k of GRID_KEYS)
+        if (stats[k])
+            out[k] = stats[k] * STAT_PER_LEVEL[k];
+    return out;
+}
+/** What's wrong with an allocation, or null: no stat past its cap at the Legion level, no overspending. */
+export function allocationProblem(a) {
+    for (const k of GRID_KEYS) {
+        const n = a.stats[k] ?? 0;
+        if (!n)
+            continue;
+        const cap = statCap(k, a.legionLevel);
+        if (n > cap) {
+            if (!cap)
+                return `${STAT_LABELS[k]} opens at Legion level ${EXPANDED_CAPS[0].level.toLocaleString('en-US')}.`;
+            return `${STAT_LABELS[k]} goes up to level ${cap}${cap < STAT_MAX_LEVEL[k] ? ' at this Legion level' : ''}.`;
+        }
+    }
+    const spent = pointsSpent(a.stats);
+    if (spent > a.points)
+        return `${spent} points are spent, but the Legion has ${a.points}.`;
+    return null;
+}
+/**
+ * The best allocation for linear weights (value per stat level, e.g. damage per level): with every level costing one
+ * point, the open stats fill highest weight first, each to its cap. Stats without a positive weight get nothing.
+ */
+export function suggestStats(weights, points, legionLevel) {
+    const out = {};
+    let left = Math.max(0, Math.trunc(points));
+    const order = GRID_KEYS.filter((k) => (weights[k] ?? 0) > 0 && statUnlocked(k, legionLevel)).sort((a, b) => weights[b] - weights[a]);
+    for (const k of order) {
+        if (!left)
+            break;
+        const n = Math.min(statCap(k, legionLevel), left);
+        out[k] = n;
+        left -= n;
+    }
+    return out;
+}
+/** Valid stat levels: known stats, whole numbers within each stat's cap, zeros dropped. */
+export function statsFrom(raw) {
+    if (!isObject(raw))
+        return {};
+    const out = {};
+    for (const k of GRID_KEYS) {
+        const n = int(raw[k], 0, STAT_MAX_LEVEL[k]);
+        if (n)
+            out[k] = n;
+    }
+    return out;
+}
+/** Valid owned event blocks: known blocks at one of their values, each within its copies. */
+export function ownedBlocksFrom(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const x of raw) {
+        if (!isObject(x))
+            continue;
+        const def = eventBlock(String(x.id));
+        if (!def || !def.values.includes(x.value))
+            continue;
+        if (out.filter((b) => b.id === def.id).length >= def.copies)
+            continue;
+        out.push({ id: def.id, value: x.value });
+    }
+    return out;
+}
+export const emptyStatPreset = (i) => ({ name: defaultPresetName(i), stats: {} });
+export const emptySharedPoints = () => ({ presets: Array.from({ length: STAT_PRESETS }, (_, i) => emptyStatPreset(i)), active: 0, blocks: [] });
+/** A preset name trimmed to PRESET_NAME_MAX, or the default for its slot when blank. */
+export function presetName(raw, i) {
+    const s = typeof raw === 'string' ? raw.replace(/\s+/g, ' ').trim().slice(0, PRESET_NAME_MAX) : '';
+    return s || defaultPresetName(i);
+}
+/** A stored points part as a valid one: always 10 presets, missing ones empty. Anything else (absent, older rows) is empty. */
+export function sharedPointsFrom(raw) {
+    if (!isObject(raw))
+        return emptySharedPoints();
+    const list = Array.isArray(raw.presets) ? raw.presets : [];
+    const presets = Array.from({ length: STAT_PRESETS }, (_, i) => {
+        const p = list[i];
+        return isObject(p) ? { name: presetName(p.name, i), stats: statsFrom(p.stats) } : emptyStatPreset(i);
+    });
+    return { presets, active: int(raw.active, 0, STAT_PRESETS - 1) ?? 0, blocks: ownedBlocksFrom(raw.blocks) };
+}
+/** Whether a stored world Legion has the points part (a row written by an app that knows v.272). */
+export const hasPoints = (legion) => isObject(legion) && isObject(legion.points);
+/** Legion Champion slots: 4, and a 5th once four Champions are rank S or higher. */
+export const CHAMPION_SLOTS = 5;
+export const CHAMPION_FIFTH_SLOT_RANK = 'S';
+/** Open Champion slots for the Champions' ranks (C, B … SSS; anything below B counts as none). */
+export function championSlotsOpen(ranks) {
+    const at = LEGION_RANKS.indexOf(CHAMPION_FIFTH_SLOT_RANK);
+    return ranks.filter((r) => LEGION_RANKS.indexOf(r) >= at).length >= 4 ? CHAMPION_SLOTS : 4;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xforge-dev/forge-kit",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Shared auth, app registry and UI for xForge apps",
   "license": "MIT",
   "repository": {