@jjlmoya/utils-games-development 1.63.0 → 1.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-games-development",
-    "version": "1.63.0",
+    "version": "1.64.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",

package/src/category/index.ts

@@ -6,10 +6,11 @@ import { saveFileEditor } from '../tool/saveFileEditor/entry';
 import { steamBbcodeTranslator } from '../tool/steamBbcodeTranslator/entry';
 import { gameUiAccessibilityTester } from '../tool/gameUIAccessibilityTester/entry';
 import { hitboxHurtboxAnimator } from '../tool/hitboxHurtboxAnimator/entry';
+import { damageFormulaLab } from '../tool/damageFormulaLab/entry';
 
 export const gamesCategory: GamesCategoryEntry = {
   icon: 'mdi:gamepad-variant',
-  tools: [steamCapsuleGenerator, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, steamBbcodeTranslator, gameUiAccessibilityTester, hitboxHurtboxAnimator],
+  tools: [steamCapsuleGenerator, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, steamBbcodeTranslator, gameUiAccessibilityTester, hitboxHurtboxAnimator, damageFormulaLab],
   i18n: {
     de: () => import('./i18n/de').then((m) => m.content),
     en: () => import('./i18n/en').then((m) => m.content),

package/src/entries.ts

@@ -18,6 +18,8 @@ export { pixelArtPaletteSwapper } from './tool/pixelArtPaletteSwapper/entry';
 export type { PixelArtPaletteSwapperUI, PixelArtPaletteSwapperLocaleContent } from './tool/pixelArtPaletteSwapper/entry';
 export { hitboxHurtboxAnimator } from './tool/hitboxHurtboxAnimator/entry';
 export type { HitboxHurtboxAnimatorUI, HitboxHurtboxAnimatorLocaleContent } from './tool/hitboxHurtboxAnimator/entry';
+export { damageFormulaLab } from './tool/damageFormulaLab/entry';
+export type { DamageFormulaLabUI, DamageFormulaLabLocaleContent } from './tool/damageFormulaLab/entry';
 export { gamesCategory } from './category';
 import { steamCapsuleGenerator } from './tool/steamCapsuleGenerator/entry';
 import { itchioGameTester } from './tool/itchioGameTester/entry';
@@ -30,5 +32,6 @@ import { retroSfxGenerator } from './tool/retroSfxGenerator/entry';
 import { pixelArtPaletteSwapper } from './tool/pixelArtPaletteSwapper/entry';
 import { gameUiAccessibilityTester } from './tool/gameUIAccessibilityTester/entry';
 import { hitboxHurtboxAnimator } from './tool/hitboxHurtboxAnimator/entry';
+import { damageFormulaLab } from './tool/damageFormulaLab/entry';
 
-export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, localizationSanitizer, steamBbcodeTranslator, retroSfxGenerator, pixelArtPaletteSwapper, gameUiAccessibilityTester, hitboxHurtboxAnimator];
+export const ALL_ENTRIES = [steamCapsuleGenerator, itchioGameTester, spriteSheetPacker, audioLoopPointFinder, saveFileEditor, localizationSanitizer, steamBbcodeTranslator, retroSfxGenerator, pixelArtPaletteSwapper, gameUiAccessibilityTester, hitboxHurtboxAnimator, damageFormulaLab];

package/src/index.ts

@@ -22,5 +22,6 @@ export { RETRO_SFX_GENERATOR_TOOL, retroSfxGenerator } from './tool/retroSfxGene
 export { PIXEL_ART_PALETTE_SWAPPER_TOOL, pixelArtPaletteSwapper } from './tool/pixelArtPaletteSwapper';
 export { GAME_UI_ACCESSIBILITY_TESTER_TOOL, gameUiAccessibilityTester } from './tool/gameUIAccessibilityTester';
 export { HITBOX_HURTBOX_ANIMATOR_TOOL, hitboxHurtboxAnimator } from './tool/hitboxHurtboxAnimator';
+export { DAMAGE_FORMULA_LAB_TOOL, damageFormulaLab } from './tool/damageFormulaLab';
 
 export type { ToolLocaleContent as GamesToolLocaleContent } from './types';

package/src/tests/locale_completeness.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest';
 import { ALL_TOOLS } from '../tools';
 
 describe('Locale Completeness Validation', () => {
-  it('eleven tools are registered', () => {
-    expect(ALL_TOOLS.length).toBe(11);
+  it('twelve tools are registered', () => {
+    expect(ALL_TOOLS.length).toBe(12);
   });
 });

package/src/tests/tool_validation.test.ts

@@ -4,8 +4,8 @@ import { gamesCategory } from '../data';
 
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
-    it('should have 11 tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(11);
+    it('should have 12 tools in ALL_TOOLS', () => {
+      expect(ALL_TOOLS.length).toBe(12);
     });
 
     it('gamesCategory should be defined', () => {

package/src/tool/damageFormulaLab/bibliography.astro

@@ -0,0 +1,24 @@
+---
+import type { BibliographyEntry } from '../../types';
+
+interface Props {
+  title?: string;
+  entries?: BibliographyEntry[];
+}
+
+const { title = 'References', entries = [] } = Astro.props;
+---
+
+{entries.length > 0 && (
+  <section class="damage-lab-references" aria-labelledby="damage-lab-reference-title">
+    <h2 id="damage-lab-reference-title">{title}</h2>
+    <ul>
+      {entries.map((entry) => <li><a href={entry.url} rel="noopener noreferrer" target="_blank">{entry.name}</a></li>)}
+    </ul>
+  </section>
+)}
+
+<style>
+  .damage-lab-references { margin-block: 2rem; }
+  .damage-lab-references a { color: var(--n-primary); }
+</style>

package/src/tool/damageFormulaLab/bibliography.ts

@@ -0,0 +1,10 @@
+export const bibliographyEntries = [
+  {
+    name: "Game Balance Concepts: Numeric Relationships",
+    url: "https://gamebalanceconcepts.wordpress.com/2010/07/14/level-2-numeric-relationships/",
+  },
+  {
+    name: "Oracle Numerical Computation Guide: What Is IEEE Arithmetic?",
+    url: "https://docs.oracle.com/cd/E37069_01/html/E39019/z4000ac019127.html",
+  },
+];

package/src/tool/damageFormulaLab/component.astro

@@ -0,0 +1,178 @@
+---
+import type { DamageFormulaLabUI } from './ui';
+import './damage-formula-lab.css';
+
+interface Props {
+  ui: DamageFormulaLabUI;
+}
+
+const { ui } = Astro.props;
+
+const coreInputs = [
+  ['attack', ui.attackLabel, 0, 100000, 1],
+  ['defense', ui.defenseLabel, 0, 100000, 1],
+  ['health', ui.healthLabel, 1, 10000000, 1],
+  ['attacksPerSecond', ui.cadenceLabel, 0.01, 100, 0.05],
+] as const;
+
+const advancedInputs = [
+  ['level', ui.levelLabel, 1, 999, 1],
+  ['power', ui.powerLabel, 0, 100, 0.05],
+  ['resistance', ui.resistanceLabel, 0, 100, 1],
+  ['flat', ui.flatLabel, -100000, 100000, 1],
+  ['criticalChance', ui.criticalChanceLabel, 0, 100, 1],
+  ['criticalMultiplier', ui.criticalMultiplierLabel, 1, 20, 0.05],
+] as const;
+---
+
+<section class="damage-lab" data-damage-lab>
+  <script is:inline type="application/json" data-damage-ui set:html={JSON.stringify(ui)} />
+
+  <header class="damage-lab-header">
+    <p>{ui.onboarding}</p>
+    <span>{ui.localNote}</span>
+  </header>
+
+  <section class="damage-lab-composer" aria-labelledby="damage-lab-formulas-title">
+    <div class="damage-lab-heading">
+      <h2 id="damage-lab-formulas-title">{ui.formulaDeck}</h2>
+      <div class="damage-lab-presets" aria-label="Formula presets">
+        <button type="button" data-preset="linear">{ui.presetLinear}</button>
+        <button type="button" data-preset="ratio">{ui.presetRatio}</button>
+        <button type="button" data-preset="level">{ui.presetLevel}</button>
+      </div>
+    </div>
+    <div class="damage-lab-formulas">
+      <label class="damage-lab-formula damage-lab-formula-a">
+        <span><i aria-hidden="true"></i>{ui.formulaALabel}</span>
+        <input name="formulaA" type="text" spellcheck="false" autocomplete="off" />
+      </label>
+      <label class="damage-lab-formula damage-lab-formula-b">
+        <span><i aria-hidden="true"></i>{ui.formulaBLabel}</span>
+        <input name="formulaB" type="text" spellcheck="false" autocomplete="off" />
+      </label>
+    </div>
+    <details class="damage-lab-language">
+      <summary>Formula language</summary>
+      <p>{ui.formulaHint}<br />{ui.formulaFunctions}</p>
+    </details>
+  </section>
+
+  <section class="damage-lab-tuning" aria-labelledby="damage-lab-tuning-title">
+    <div class="damage-lab-heading">
+      <h2 id="damage-lab-tuning-title">{ui.combatInputs}</h2>
+      <div class="damage-lab-scenarios" aria-label={ui.scenariosTitle}>
+        <button type="button" data-scenario="skirmisher">{ui.scenarioSkirmisher}</button>
+        <button type="button" data-scenario="guardian">{ui.scenarioGuardian}</button>
+        <button type="button" data-scenario="boss">{ui.scenarioBoss}</button>
+        <button type="button" data-scenario="custom">{ui.scenarioCustom}</button>
+      </div>
+    </div>
+    <div class="damage-lab-core-inputs">
+      {coreInputs.map(([name, label, min, max, step]) => (
+        <label>
+          <span>{label}</span>
+          <input name={name} type="number" min={min} max={max} step={step} inputmode="decimal" />
+        </label>
+      ))}
+    </div>
+    <details class="damage-lab-advanced">
+      <summary>Advanced combat and engine rules</summary>
+      <div class="damage-lab-advanced-grid">
+        {advancedInputs.map(([name, label, min, max, step]) => (
+          <label>
+            <span>{label}</span>
+            <input name={name} type="number" min={min} max={max} step={step} inputmode="decimal" />
+          </label>
+        ))}
+      </div>
+      <fieldset class="damage-lab-choice">
+        <legend>{ui.roundingLabel}</legend>
+        <button type="button" data-rounding="none">{ui.roundingNone}</button>
+        <button type="button" data-rounding="floor">{ui.roundingFloor}</button>
+        <button type="button" data-rounding="round">{ui.roundingRound}</button>
+        <button type="button" data-rounding="ceil">{ui.roundingCeil}</button>
+      </fieldset>
+      <fieldset class="damage-lab-choice">
+        <legend>{ui.orderLabel}</legend>
+        <button type="button" data-order="resistance-first">{ui.resistanceFirst}</button>
+        <button type="button" data-order="flat-first">{ui.flatFirst}</button>
+      </fieldset>
+    </details>
+  </section>
+
+  <section class="damage-lab-result" aria-labelledby="damage-lab-result-title">
+    <div class="damage-lab-result-heading">
+      <div><span>Live model</span><h2 id="damage-lab-result-title">{ui.runLabel}</h2></div>
+      <div class="damage-lab-gap"><small>{ui.resultDifference}</small><strong data-result="gap">0</strong></div>
+    </div>
+    <div class="damage-lab-totals">
+      <article>
+        <span>{ui.formulaAName}</span>
+        <strong data-result="a-damage">0</strong>
+        <small>{ui.resultDamage}</small>
+        <dl><div><dt>{ui.resultHits}</dt><dd data-result="a-hits">0</dd></div><div><dt>{ui.resultTtk}</dt><dd data-result="a-ttk">0 s</dd></div></dl>
+      </article>
+      <article>
+        <span>{ui.formulaBName}</span>
+        <strong data-result="b-damage">0</strong>
+        <small>{ui.resultDamage}</small>
+        <dl><div><dt>{ui.resultHits}</dt><dd data-result="b-hits">0</dd></div><div><dt>{ui.resultTtk}</dt><dd data-result="b-ttk">0 s</dd></div></dl>
+      </article>
+    </div>
+    <div class="damage-lab-curve-heading">
+      <div><h3>{ui.curveTitle}</h3><p>{ui.curveCaption}</p></div>
+      <span><b data-curve-max>0</b> max</span>
+    </div>
+    <svg class="damage-lab-chart" data-chart viewBox="0 0 100 100" preserveAspectRatio="none" role="img" aria-label={ui.curveTitle}>
+      <path class="damage-lab-guide" d="M0 25 H100 M0 50 H100 M0 75 H100" />
+      <path class="damage-lab-curve damage-lab-curve-a" data-curve="a" d="" />
+      <path class="damage-lab-curve damage-lab-curve-b" data-curve="b" d="" />
+    </svg>
+    <div class="damage-lab-legend"><span>{ui.formulaAName}</span><span>{ui.formulaBName}</span></div>
+  </section>
+
+  <details class="damage-lab-secondary">
+    <summary>{ui.heatmapTitle} + {ui.diagnosticsTitle}</summary>
+    <div class="damage-lab-notes">
+      <section class="damage-lab-pressure" aria-labelledby="damage-lab-heatmap-title">
+        <h2 id="damage-lab-heatmap-title">{ui.heatmapTitle}</h2>
+        <p>{ui.heatmapCaption}</p>
+        <div class="damage-lab-axis">{ui.attackAxis}</div>
+        <div class="damage-lab-heatmap" data-heatmap></div>
+        <small>{ui.defenseAxis}</small>
+      </section>
+      <section class="damage-lab-diagnostics" aria-labelledby="damage-lab-diagnostics-title">
+        <h2 id="damage-lab-diagnostics-title">{ui.diagnosticsTitle}</h2>
+        <ul data-diagnostics></ul>
+        <p>{ui.limitationDisclosure}</p>
+      </section>
+    </div>
+  </details>
+
+  <details class="damage-lab-export-panel">
+    <summary>{ui.exportTitle}</summary>
+    <footer class="damage-lab-exports">
+      <p>{ui.privacyDisclosure}</p>
+      <div class="damage-lab-actions">
+        <button type="button" data-share>{ui.copyLink}</button>
+        <button type="button" data-csv>{ui.exportCsv}</button>
+        <button type="button" data-json>{ui.exportJson}</button>
+        <label>{ui.importJson}<input type="file" accept="application/json,.json" data-import /></label>
+        <button type="button" data-png>{ui.exportPng}</button>
+        <button type="button" data-reset>{ui.reset}</button>
+      </div>
+      <p class="damage-lab-status" data-status aria-live="polite"></p>
+    </footer>
+  </details>
+</section>
+
+<script>
+  import { mountDamageFormulaLab } from './controller';
+  import type { DamageFormulaLabUI } from './ui';
+
+  document.querySelectorAll<HTMLElement>('[data-damage-lab]').forEach((root) => {
+    const source = root.querySelector<HTMLScriptElement>('[data-damage-ui]');
+    if (source?.textContent) mountDamageFormulaLab(root, JSON.parse(source.textContent) as DamageFormulaLabUI);
+  });
+</script>

package/src/tool/damageFormulaLab/controller.ts

@@ -0,0 +1,235 @@
+import { renderLab } from "./dom-views";
+import {
+  configFromHash,
+  defaultConfig,
+  formulaPresets,
+  parseConfig,
+  scenarios,
+} from "./model";
+import type { LabConfig } from "./model";
+import { loadPreferences, savePreferences } from "./storage";
+import {
+  copyShareLink,
+  exportChartPng,
+  exportCsv,
+  exportJson,
+} from "./transfers";
+import type { DamageFormulaLabUI } from "./ui";
+
+type Update = (config: LabConfig) => void;
+type GetConfig = () => LabConfig;
+
+function input(root: HTMLElement, name: string): HTMLInputElement | null {
+  return root.querySelector<HTMLInputElement>(`[name="${name}"]`);
+}
+
+function numberValue(
+  root: HTMLElement,
+  name: string,
+  fallback: number,
+): number {
+  const value = Number(input(root, name)?.value);
+  return Number.isFinite(value) ? value : fallback;
+}
+
+function setActive(root: HTMLElement, selector: string, value: string): void {
+  root.querySelectorAll<HTMLElement>(selector).forEach((item) => {
+    const candidate = item.dataset.rounding ?? item.dataset.order;
+    item.dataset.active = String(candidate === value);
+  });
+}
+
+function writeInputs(root: HTMLElement, config: LabConfig): void {
+  const values: Record<string, number | string> = {
+    formulaA: config.formulaA,
+    formulaB: config.formulaB,
+    ...config.variables,
+    health: config.settings.health,
+    attacksPerSecond: config.settings.attacksPerSecond,
+  };
+  Object.entries(values).forEach(([name, value]) => {
+    const field = input(root, name);
+    if (field) field.value = String(value);
+  });
+  setActive(root, "[data-rounding]", config.settings.rounding);
+  setActive(root, "[data-order]", config.settings.modifierOrder);
+}
+
+function readVariables(
+  root: HTMLElement,
+  current: LabConfig,
+): Record<string, number> {
+  return Object.fromEntries(
+    Object.keys(current.variables).map((name) => [
+      name,
+      numberValue(
+        root,
+        name,
+        current.variables[name as keyof typeof current.variables],
+      ),
+    ]),
+  );
+}
+
+function readConfig(root: HTMLElement, current: LabConfig): LabConfig {
+  return parseConfig({
+    ...current,
+    formulaA: input(root, "formulaA")?.value,
+    formulaB: input(root, "formulaB")?.value,
+    variables: readVariables(root, current),
+    settings: {
+      ...current.settings,
+      health: numberValue(root, "health", current.settings.health),
+      attacksPerSecond: numberValue(
+        root,
+        "attacksPerSecond",
+        current.settings.attacksPerSecond,
+      ),
+    },
+  });
+}
+
+function save(config: LabConfig): void {
+  savePreferences({
+    formulaA: config.formulaA,
+    formulaB: config.formulaB,
+    rounding: config.settings.rounding,
+    modifierOrder: config.settings.modifierOrder,
+  });
+}
+
+function initialConfig(): LabConfig {
+  const preferences = loadPreferences();
+  return (
+    configFromHash(location.hash) ?? {
+      ...structuredClone(defaultConfig),
+      formulaA: preferences.formulaA,
+      formulaB: preferences.formulaB,
+      settings: {
+        ...defaultConfig.settings,
+        rounding: preferences.rounding,
+        modifierOrder: preferences.modifierOrder,
+      },
+    }
+  );
+}
+
+function applyScenario(config: LabConfig, name: string): LabConfig {
+  const scenario = scenarios[name];
+  if (!scenario) return config;
+  const { health, ...variables } = scenario;
+  return {
+    ...config,
+    variables: { ...config.variables, ...variables },
+    settings: { ...config.settings, health },
+  };
+}
+
+function bindModes(root: HTMLElement, get: GetConfig, update: Update): void {
+  root
+    .querySelectorAll<HTMLButtonElement>("[data-rounding]")
+    .forEach((button) =>
+      button.addEventListener("click", () => {
+        const config = get();
+        update({
+          ...config,
+          settings: {
+            ...config.settings,
+            rounding: button.dataset
+              .rounding as LabConfig["settings"]["rounding"],
+          },
+        });
+      }),
+    );
+  root.querySelectorAll<HTMLButtonElement>("[data-order]").forEach((button) =>
+    button.addEventListener("click", () => {
+      const config = get();
+      update({
+        ...config,
+        settings: {
+          ...config.settings,
+          modifierOrder: button.dataset
+            .order as LabConfig["settings"]["modifierOrder"],
+        },
+      });
+    }),
+  );
+}
+
+function bindPresets(root: HTMLElement, get: GetConfig, update: Update): void {
+  root.querySelectorAll<HTMLButtonElement>("[data-preset]").forEach((button) =>
+    button.addEventListener("click", () => {
+      const formula =
+        formulaPresets[button.dataset.preset as keyof typeof formulaPresets];
+      update({ ...get(), formulaB: formula });
+    }),
+  );
+  root
+    .querySelectorAll<HTMLButtonElement>("[data-scenario]")
+    .forEach((button) =>
+      button.addEventListener("click", () => {
+        update(applyScenario(get(), button.dataset.scenario ?? ""));
+      }),
+    );
+}
+
+function bindImport(
+  root: HTMLElement,
+  update: Update,
+  ui: DamageFormulaLabUI,
+): void {
+  const picker = root.querySelector<HTMLInputElement>("[data-import]");
+  picker?.addEventListener("change", async () => {
+    try {
+      const file = picker.files?.[0];
+      if (file) update(parseConfig(JSON.parse(await file.text())));
+    } catch {
+      const status = root.querySelector<HTMLElement>("[data-status]");
+      if (status) status.textContent = ui.importError;
+    }
+  });
+}
+
+function bindExports(
+  root: HTMLElement,
+  get: GetConfig,
+  update: Update,
+  ui: DamageFormulaLabUI,
+): void {
+  root
+    .querySelector("[data-reset]")
+    ?.addEventListener("click", () => update(structuredClone(defaultConfig)));
+  root
+    .querySelector("[data-json]")
+    ?.addEventListener("click", () => exportJson(get()));
+  root
+    .querySelector("[data-csv]")
+    ?.addEventListener("click", () => exportCsv(get()));
+  root
+    .querySelector("[data-png]")
+    ?.addEventListener("click", () => exportChartPng(root));
+  root.querySelector("[data-share]")?.addEventListener("click", async () => {
+    await copyShareLink(get());
+    const status = root.querySelector<HTMLElement>("[data-status]");
+    if (status) status.textContent = ui.copiedStatus;
+  });
+  bindImport(root, update, ui);
+}
+
+export function mountDamageFormulaLab(
+  root: HTMLElement,
+  ui: DamageFormulaLabUI,
+): void {
+  let config = initialConfig();
+  const update: Update = (next) => {
+    config = next;
+    writeInputs(root, config);
+    save(config);
+    renderLab(root, config, ui);
+  };
+  root.addEventListener("input", () => update(readConfig(root, config)));
+  bindModes(root, () => config, update);
+  bindPresets(root, () => config, update);
+  bindExports(root, () => config, update, ui);
+  update(config);
+}