ugly-game 0.5.1 → 0.5.2

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export * from './mat4';
 export * from './noise';
 export * from './moat';
 export * from './stateIR';
+export * from './playtestIR';
+export * from './visualIR';
 export * from './gpuShadow';
 export * from './input/resolve';
 export * from './input/browserBackend';

package/dist/index.js

@@ -5,6 +5,8 @@ export * from './mat4';
 export * from './noise';
 export * from './moat';
 export * from './stateIR';
+export * from './playtestIR';
+export * from './visualIR';
 export * from './gpuShadow';
 export * from './input/resolve';
 export * from './input/browserBackend';

package/dist/playtestIR.d.ts

@@ -0,0 +1,60 @@
+export interface PlayEvent {
+    tick: number;
+    kind: string;
+    note: string;
+}
+export interface PlaytestDigest {
+    wallSeconds: number;
+    ticks: number;
+    rewards: PlayEvent[];
+    rewardCadenceSec: number | null;
+    longestDrySpellSec: number;
+    frictions: PlayEvent[];
+    actions: number;
+    failedActions: number;
+    undos: number;
+    varietyScore: number;
+    featuresUsed: string[];
+    progress: Record<string, number>;
+    affordances: string[];
+    summary: string;
+}
+/** Options for `digest()` — the game supplies the bits only it knows. */
+export interface DigestInput {
+    wallSeconds: number;
+    nowTick: number;
+    progress?: Record<string, number>;
+    affordances?: string[];
+    /** Extra domain notes appended to the summary (e.g. "⚠ stuck for 8s"). */
+    extraNotes?: string[];
+    /** Distinct things the player TOUCHED beyond `feature()` (e.g. building types placed) — added to varietyScore. */
+    extraVariety?: number;
+}
+/** Records a play session and distils it into fun/ease evidence. FRAMEWORK: the game detects what counts as a
+ *  reward/friction and calls these; the recorder does the cadence/variety/summary math. Ticks are the game's own. */
+export declare class SessionRecorder {
+    private readonly startTick;
+    private lastRewardTick;
+    private longestDry;
+    private readonly rewards;
+    private readonly frictions;
+    private readonly features;
+    private actionN;
+    private failedN;
+    private undoN;
+    constructor(startTick?: number);
+    /** A rewarding moment happened (first-delivery, milestone, unlock…). Updates the reward cadence + dry-spell. */
+    reward(tick: number, kind: string, note: string): void;
+    /** A friction moment (failed action, being stuck, an unresolved warning). */
+    friction(tick: number, kind: string, note: string): void;
+    /** A player action — `failed`/`undo` feed the ease signals. */
+    action(opts?: {
+        failed?: boolean;
+        undo?: boolean;
+    }): void;
+    /** A mechanic the player actually engaged (for variety/depth). */
+    feature(name: string): void;
+    get rewardCount(): number;
+    /** Distil the session into the digest a grader reads. `fps` scales tick-gaps to seconds (default 60). */
+    digest(input: DigestInput, fps?: number): PlaytestDigest;
+}

package/dist/playtestIR.js

@@ -0,0 +1,64 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ugly-game PLAYTEST IR — the SUBJECTIVE layer of the IR platform.
+//
+// stateIR answers "is it BROKEN?"; this answers "is it FUN and LEARNABLE?" by recording a play SESSION and
+// distilling it into evidence a simulated player (or an AI grader) reads to rate the experience:
+//   • REWARD events + their CADENCE + longest DRY SPELL  — the core "is it fun?" signal (long gaps = boring)
+//   • FRICTION events + failed actions / undos            — the core "is it easy?" signal
+//   • VARIETY (features engaged) + game PROGRESS counters + AFFORDANCES (what's discoverable next)
+//
+// This module is GENERIC: a game feeds it (`reward`/`friction`/`action`/`feature`) from its own delta-detection
+// (which items were delivered, which tech unlocked — that part is game-specific), then `digest()` computes the
+// cadence/dry-spell/variety and formats the summary. Deterministic given the same feed. Graduated from Cogsworth.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Records a play session and distils it into fun/ease evidence. FRAMEWORK: the game detects what counts as a
+ *  reward/friction and calls these; the recorder does the cadence/variety/summary math. Ticks are the game's own. */
+export class SessionRecorder {
+    startTick;
+    lastRewardTick;
+    longestDry = 0;
+    rewards = [];
+    frictions = [];
+    features = new Set();
+    actionN = 0;
+    failedN = 0;
+    undoN = 0;
+    constructor(startTick = 0) { this.startTick = startTick; this.lastRewardTick = startTick; }
+    /** A rewarding moment happened (first-delivery, milestone, unlock…). Updates the reward cadence + dry-spell. */
+    reward(tick, kind, note) {
+        this.rewards.push({ tick, kind, note });
+        this.longestDry = Math.max(this.longestDry, (tick - this.lastRewardTick) / 60);
+        this.lastRewardTick = tick;
+    }
+    /** A friction moment (failed action, being stuck, an unresolved warning). */
+    friction(tick, kind, note) { this.frictions.push({ tick, kind, note }); }
+    /** A player action — `failed`/`undo` feed the ease signals. */
+    action(opts = {}) { this.actionN++; if (opts.failed)
+        this.failedN++; if (opts.undo)
+        this.undoN++; }
+    /** A mechanic the player actually engaged (for variety/depth). */
+    feature(name) { this.features.add(name); }
+    get rewardCount() { return this.rewards.length; }
+    /** Distil the session into the digest a grader reads. `fps` scales tick-gaps to seconds (default 60). */
+    digest(input, fps = 60) {
+        const ticks = input.nowTick - this.startTick;
+        const cadence = this.rewards.length > 0 ? +(input.wallSeconds / this.rewards.length).toFixed(1) : null;
+        const feats = [...this.features].sort();
+        const varietyScore = feats.length + (input.extraVariety ?? 0);
+        const progress = input.progress ?? {};
+        const affordances = input.affordances ?? [];
+        const summary = [
+            `Over ${input.wallSeconds.toFixed(0)}s (${ticks} ticks): ${this.actionN} actions (${this.failedN} failed, ${this.undoN} undone).`,
+            Object.keys(progress).length ? `Progress: ${Object.entries(progress).map(([k, v]) => `${k} ${v}`).join(', ')}.` : '',
+            `${this.rewards.length} reward moments${cadence !== null ? ` (one about every ${cadence}s; longest dry spell ${this.longestDry.toFixed(0)}s)` : ' (none — nothing rewarding happened)'}.`,
+            `Engaged: ${feats.length ? feats.join(', ') : 'only the basics'}.`,
+            ...(input.extraNotes ?? []),
+        ].filter(Boolean).join(' ');
+        return {
+            wallSeconds: +input.wallSeconds.toFixed(1), ticks,
+            rewards: this.rewards, rewardCadenceSec: cadence, longestDrySpellSec: +this.longestDry.toFixed(1),
+            frictions: this.frictions, actions: this.actionN, failedActions: this.failedN, undos: this.undoN,
+            varietyScore, featuresUsed: feats, progress, affordances, summary,
+        };
+    }
+}

package/dist/visualIR.d.ts

@@ -0,0 +1,28 @@
+/** The minimal per-box info the summary reads (RGB in 0..1, emissive strength, world height). */
+export interface SceneBox {
+    y: number;
+    emissive: number;
+    r: number;
+    g: number;
+    b: number;
+}
+export interface SceneSummary {
+    instances: number;
+    distinctColours: number;
+    palette: string[];
+    emissiveCoverage: number;
+    emissiveMean: number;
+    heightSpread: number;
+    motion: number;
+    notes: string[];
+}
+export interface SummaryThresholds {
+    monochromeAtOrBelow?: number;
+    underlitBelow?: number;
+    livelyAtOrAbove?: number;
+    flatBelow?: number;
+}
+/** Summarise a scene's boxes + a motion count into actionable attractiveness signals. Pure. The game filters
+ *  which boxes count as "content" (e.g. skip the ground plane) before calling. Notes fire off simple thresholds
+ *  (overridable) so the output maps straight to a fix. */
+export declare function summarizeScene(boxes: Iterable<SceneBox>, motion: number, th?: SummaryThresholds): SceneSummary;

package/dist/visualIR.js

@@ -0,0 +1,59 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ugly-game VISUAL IR — attractiveness as STRUCTURED, ACTIONABLE data instead of a screenshot.
+//
+// The renderer already emits a structured scene (typed boxes: position + colour + emissive), so we can read the
+// composition directly and report precise, fixable signals — palette diversity, how much of the scene glows,
+// vertical layering — plus a caller-supplied MOTION count (how many parts are moving: the "living scene"). A
+// screenshot says "looks flat"; this says "3 colours, 2% self-lit, nothing moving → monochrome + under-lit +
+// static", which is a fix list.
+//
+// This module is GENERIC: the game hands it the scene's boxes (whatever subset counts as "content") + a motion
+// count from its own state; `summarizeScene` computes the palette/glow/layering + actionable notes. It's the
+// visual arm of the IR platform (fun/ease = playtestIR, "is it broken?" = stateIR, "does it look good?" = here).
+// Graduated from Cogsworth. Screenshots stay a secondary spot-check for taste/composition structure can't see.
+// ─────────────────────────────────────────────────────────────────────────────
+const approxHex = (r, g, b) => '#' + [r, g, b].map((c) => Math.round(Math.min(1, Math.max(0, c)) * 255).toString(16).padStart(2, '0')).join('');
+/** Summarise a scene's boxes + a motion count into actionable attractiveness signals. Pure. The game filters
+ *  which boxes count as "content" (e.g. skip the ground plane) before calling. Notes fire off simple thresholds
+ *  (overridable) so the output maps straight to a fix. */
+export function summarizeScene(boxes, motion, th = {}) {
+    const monoAt = th.monochromeAtOrBelow ?? 3, underlit = th.underlitBelow ?? 0.06, lively = th.livelyAtOrAbove ?? 20, flat = th.flatBelow ?? 1.2;
+    const colours = new Map();
+    let emisSum = 0, lit = 0, minY = Infinity, maxY = -Infinity, n = 0;
+    for (const bx of boxes) {
+        n++;
+        const key = `${Math.round(bx.r * 16)},${Math.round(bx.g * 16)},${Math.round(bx.b * 16)}`;
+        const c = colours.get(key);
+        if (c)
+            c.n++;
+        else
+            colours.set(key, { n: 1, r: bx.r, g: bx.g, b: bx.b });
+        emisSum += bx.emissive;
+        if (bx.emissive > 0.3)
+            lit++;
+        if (bx.y < minY)
+            minY = bx.y;
+        if (bx.y > maxY)
+            maxY = bx.y;
+    }
+    const palette = [...colours.values()].sort((a, b) => b.n - a.n).slice(0, 6).map((c) => approxHex(c.r, c.g, c.b));
+    const emissiveCoverage = n ? lit / n : 0, emissiveMean = n ? emisSum / n : 0, heightSpread = maxY > minY ? maxY - minY : 0;
+    const notes = [];
+    if (palette.length <= monoAt)
+        notes.push(`only ${palette.length} dominant colours — reads monochrome`);
+    if (emissiveCoverage < underlit)
+        notes.push('little glow — under-lit / flat');
+    if (motion === 0)
+        notes.push('nothing is moving — reads static/dead');
+    else if (motion >= lively)
+        notes.push(`lively — ${motion} moving parts on screen`);
+    if (heightSpread < flat)
+        notes.push('low vertical variety — reads flat (little layering)');
+    if (!notes.length)
+        notes.push('cohesive palette, good glow, moving parts — reads rich + alive');
+    return {
+        instances: n, distinctColours: colours.size, palette,
+        emissiveCoverage: +emissiveCoverage.toFixed(3), emissiveMean: +emissiveMean.toFixed(3), heightSpread: +heightSpread.toFixed(2),
+        motion, notes,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-game",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "type": "module",
   "exports": {
     ".": {