@jjlmoya/utils-games-development 1.62.0 → 1.64.0

package/src/tool/damageFormulaLab/model.ts

@@ -0,0 +1,151 @@
+import type {
+  CombatSettings,
+  FormulaVariables,
+  ModifierOrder,
+  RoundingMode,
+  SweepRange,
+} from "./logic";
+
+export interface LabConfig {
+  version: 1;
+  formulaA: string;
+  formulaB: string;
+  variables: FormulaVariables;
+  settings: CombatSettings;
+  attackRange: SweepRange;
+  defenseRange: SweepRange;
+}
+
+export const defaultConfig: LabConfig = {
+  version: 1,
+  formulaA: "max(1, attack * power - defense)",
+  formulaB: "max(1, attack * power * 100 / (100 + defense))",
+  variables: {
+    attack: 80,
+    defense: 35,
+    level: 20,
+    power: 1.4,
+    resistance: 15,
+    flat: 3,
+    criticalChance: 20,
+    criticalMultiplier: 1.75,
+  },
+  settings: {
+    health: 450,
+    attacksPerSecond: 1.5,
+    rounding: "round",
+    modifierOrder: "resistance-first",
+  },
+  attackRange: { min: 40, max: 160, steps: 17 },
+  defenseRange: { min: 10, max: 90, steps: 9 },
+};
+
+export const formulaPresets = {
+  linear: "max(1, attack * power - defense)",
+  ratio: "max(1, attack * power * 100 / (100 + defense))",
+  level:
+    "max(1, ((2 * level + 10) / 250) * (attack / max(1, defense)) * power + 2)",
+};
+
+export const scenarios: Record<
+  string,
+  Partial<FormulaVariables> & { health: number }
+> = {
+  skirmisher: { defense: 20, resistance: 5, health: 220 },
+  guardian: { defense: 70, resistance: 25, health: 700 },
+  boss: { defense: 110, resistance: 35, health: 2200 },
+};
+
+function finite(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function rounding(value: unknown): RoundingMode {
+  if (value === "none" || value === "floor" || value === "ceil") return value;
+  return "round";
+}
+
+function order(value: unknown): ModifierOrder {
+  return value === "flat-first" ? "flat-first" : "resistance-first";
+}
+
+function variables(value: unknown): FormulaVariables {
+  const source =
+    typeof value === "object" && value
+      ? (value as Partial<FormulaVariables>)
+      : {};
+  const base = defaultConfig.variables;
+  return {
+    attack: finite(source.attack, base.attack),
+    defense: finite(source.defense, base.defense),
+    level: finite(source.level, base.level),
+    power: finite(source.power, base.power),
+    resistance: finite(source.resistance, base.resistance),
+    flat: finite(source.flat, base.flat),
+    criticalChance: finite(source.criticalChance, base.criticalChance),
+    criticalMultiplier: finite(
+      source.criticalMultiplier,
+      base.criticalMultiplier,
+    ),
+  };
+}
+
+function range(value: unknown, fallback: SweepRange): SweepRange {
+  const source =
+    typeof value === "object" && value ? (value as Partial<SweepRange>) : {};
+  return {
+    min: finite(source.min, fallback.min),
+    max: finite(source.max, fallback.max),
+    steps: finite(source.steps, fallback.steps),
+  };
+}
+
+function combatSettings(value: unknown): CombatSettings {
+  const source =
+    typeof value === "object" && value
+      ? (value as Partial<CombatSettings>)
+      : {};
+  return {
+    health: finite(source.health, defaultConfig.settings.health),
+    attacksPerSecond: finite(
+      source.attacksPerSecond,
+      defaultConfig.settings.attacksPerSecond,
+    ),
+    rounding: rounding(source.rounding),
+    modifierOrder: order(source.modifierOrder),
+  };
+}
+
+export function parseConfig(value: unknown): LabConfig {
+  if (typeof value !== "object" || !value)
+    throw new Error("Invalid configuration");
+  const source = value as Partial<LabConfig>;
+  return {
+    version: 1,
+    formulaA:
+      typeof source.formulaA === "string"
+        ? source.formulaA
+        : defaultConfig.formulaA,
+    formulaB:
+      typeof source.formulaB === "string"
+        ? source.formulaB
+        : defaultConfig.formulaB,
+    variables: variables(source.variables),
+    settings: combatSettings(source.settings),
+    attackRange: range(source.attackRange, defaultConfig.attackRange),
+    defenseRange: range(source.defenseRange, defaultConfig.defenseRange),
+  };
+}
+
+export function configFromHash(hash: string): LabConfig | undefined {
+  try {
+    if (!hash.startsWith("#damage=")) return undefined;
+    return parseConfig(JSON.parse(decodeURIComponent(hash.slice(8))));
+  } catch {
+    return undefined;
+  }
+}
+
+export function configToHash(config: LabConfig): string {
+  return `#damage=${encodeURIComponent(JSON.stringify(config))}`;
+}

package/src/tool/damageFormulaLab/seo.astro

@@ -0,0 +1,13 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import type { SEOSection } from '../../types';
+
+interface Props {
+  locale?: string;
+  sections?: SEOSection[];
+}
+
+const { locale = 'en', sections = [] } = Astro.props;
+---
+
+<SEORenderer content={{ locale, sections }} />

package/src/tool/damageFormulaLab/storage.ts

@@ -0,0 +1,62 @@
+import type { ModifierOrder, RoundingMode } from "./logic";
+
+export interface LabPreferences {
+  formulaA: string;
+  formulaB: string;
+  rounding: RoundingMode;
+  modifierOrder: ModifierOrder;
+}
+
+const STORAGE_KEY = "jjlmoya-damage-formula-lab";
+
+export const defaultPreferences: LabPreferences = {
+  formulaA: "max(1, attack * power - defense)",
+  formulaB: "max(1, attack * power * 100 / (100 + defense))",
+  rounding: "round",
+  modifierOrder: "resistance-first",
+};
+
+function isRounding(value: unknown): value is RoundingMode {
+  return (
+    value === "none" ||
+    value === "floor" ||
+    value === "round" ||
+    value === "ceil"
+  );
+}
+
+function isOrder(value: unknown): value is ModifierOrder {
+  return value === "resistance-first" || value === "flat-first";
+}
+
+export function loadPreferences(): LabPreferences {
+  try {
+    const parsed = JSON.parse(
+      localStorage.getItem(STORAGE_KEY) ?? "",
+    ) as Partial<LabPreferences>;
+    return {
+      formulaA:
+        typeof parsed.formulaA === "string"
+          ? parsed.formulaA
+          : defaultPreferences.formulaA,
+      formulaB:
+        typeof parsed.formulaB === "string"
+          ? parsed.formulaB
+          : defaultPreferences.formulaB,
+      rounding: isRounding(parsed.rounding)
+        ? parsed.rounding
+        : defaultPreferences.rounding,
+      modifierOrder: isOrder(parsed.modifierOrder)
+        ? parsed.modifierOrder
+        : defaultPreferences.modifierOrder,
+    };
+  } catch {
+    return { ...defaultPreferences };
+  }
+}
+
+export function savePreferences(preferences: LabPreferences): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(preferences));
+  } catch {}
+}

package/src/tool/damageFormulaLab/transfers.ts

@@ -0,0 +1,89 @@
+import { buildCurve } from "./logic";
+import { configToHash } from "./model";
+import type { LabConfig } from "./model";
+
+export function download(name: string, type: string, body: BlobPart): void {
+  const link = document.createElement("a");
+  link.href = URL.createObjectURL(new Blob([body], { type }));
+  link.download = name;
+  link.click();
+  URL.revokeObjectURL(link.href);
+}
+
+function curveRows(config: LabConfig): Array<Array<number | undefined>> {
+  const a = buildCurve(
+    config.formulaA,
+    config.variables,
+    config.settings,
+    config.attackRange,
+  );
+  const b = buildCurve(
+    config.formulaB,
+    config.variables,
+    config.settings,
+    config.attackRange,
+  );
+  return a.map((point, index) => [
+    point.attack,
+    point.defense,
+    point.roundedDamage,
+    point.hitsToKill,
+    point.timeToKill,
+    b[index]?.roundedDamage,
+    b[index]?.hitsToKill,
+    b[index]?.timeToKill,
+  ]);
+}
+
+export function exportCsv(config: LabConfig): void {
+  const header = [
+    "attack",
+    "defense",
+    "formula_a_damage",
+    "formula_a_hits",
+    "formula_a_ttk",
+    "formula_b_damage",
+    "formula_b_hits",
+    "formula_b_ttk",
+  ];
+  const body = [header, ...curveRows(config)]
+    .map((row) => row.join(","))
+    .join("\n");
+  download("damage-formula-sweep.csv", "text/csv", body);
+}
+
+export function exportJson(config: LabConfig): void {
+  download(
+    "damage-formula-lab.json",
+    "application/json",
+    JSON.stringify(config, null, 2),
+  );
+}
+
+function drawPng(image: HTMLImageElement): void {
+  const canvas = document.createElement("canvas");
+  canvas.width = 1200;
+  canvas.height = 700;
+  const context = canvas.getContext("2d");
+  if (!context) return;
+  context.fillStyle = "#f7f4ee";
+  context.fillRect(0, 0, canvas.width, canvas.height);
+  context.drawImage(image, 70, 70, 1060, 560);
+  canvas.toBlob((blob) => {
+    if (blob) download("damage-formula-curve.png", "image/png", blob);
+  }, "image/png");
+}
+
+export function exportChartPng(root: HTMLElement): void {
+  const svg = root.querySelector<SVGSVGElement>("[data-chart]");
+  if (!svg) return;
+  const source = new XMLSerializer().serializeToString(svg);
+  const image = new Image();
+  image.onload = () => drawPng(image);
+  image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(source)}`;
+}
+
+export async function copyShareLink(config: LabConfig): Promise<void> {
+  const url = `${location.origin}${location.pathname}${configToHash(config)}`;
+  await navigator.clipboard.writeText(url);
+}

package/src/tool/damageFormulaLab/ui.ts

@@ -0,0 +1,62 @@
+export interface DamageFormulaLabUI extends Record<string, string> {
+  onboarding: string;
+  localNote: string;
+  formulaDeck: string;
+  formulaALabel: string;
+  formulaBLabel: string;
+  formulaHint: string;
+  formulaFunctions: string;
+  presetLinear: string;
+  presetRatio: string;
+  presetLevel: string;
+  combatInputs: string;
+  attackLabel: string;
+  defenseLabel: string;
+  levelLabel: string;
+  powerLabel: string;
+  resistanceLabel: string;
+  flatLabel: string;
+  criticalChanceLabel: string;
+  criticalMultiplierLabel: string;
+  healthLabel: string;
+  cadenceLabel: string;
+  roundingLabel: string;
+  roundingNone: string;
+  roundingFloor: string;
+  roundingRound: string;
+  roundingCeil: string;
+  orderLabel: string;
+  resistanceFirst: string;
+  flatFirst: string;
+  runLabel: string;
+  resultDamage: string;
+  resultHits: string;
+  resultTtk: string;
+  resultDifference: string;
+  formulaAName: string;
+  formulaBName: string;
+  curveTitle: string;
+  curveCaption: string;
+  heatmapTitle: string;
+  heatmapCaption: string;
+  attackAxis: string;
+  defenseAxis: string;
+  scenariosTitle: string;
+  scenarioSkirmisher: string;
+  scenarioGuardian: string;
+  scenarioBoss: string;
+  scenarioCustom: string;
+  diagnosticsTitle: string;
+  statusBalanced: string;
+  exportTitle: string;
+  copyLink: string;
+  exportCsv: string;
+  exportJson: string;
+  importJson: string;
+  exportPng: string;
+  reset: string;
+  privacyDisclosure: string;
+  limitationDisclosure: string;
+  importError: string;
+  copiedStatus: string;
+}

package/src/tool/hitboxHurtboxAnimator/bibliography.astro

@@ -0,0 +1,12 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import type { BibliographyEntry } from '../../types';
+
+interface Props {
+  links?: BibliographyEntry[];
+}
+
+const { links = [] } = Astro.props;
+---
+
+<SharedBibliography links={links} />

package/src/tool/hitboxHurtboxAnimator/bibliography.ts

@@ -0,0 +1,10 @@
+export const bibliographyEntries = [
+  {
+    name: 'Godot Engine: Rect2 coordinate and size reference',
+    url: 'https://docs.godotengine.org/en/stable/classes/class_rect2.html',
+  },
+  {
+    name: 'Unity Manual: Sprite Editor Custom Physics Shape',
+    url: 'https://docs.unity3d.com/es/2021.1/Manual/CustomPhysicsShape.html',
+  },
+];

package/src/tool/hitboxHurtboxAnimator/canvas-interactions.ts

@@ -0,0 +1,59 @@
+import type { EditorState } from './editor-state';
+import { renderDraft, renderEditor, setStatus } from './dom-views';
+import { canvasPoint } from './canvas-metrics';
+import { shapeAtPoint } from './logic';
+import { addDrawnShape, checkpoint, moveSelected } from './project-actions';
+
+interface PointerSession {
+  start: { x: number; y: number };
+  last: { x: number; y: number };
+  dragging: boolean;
+  checkpointed: boolean;
+}
+
+export function bindCanvas(state: EditorState): void {
+  const canvas = state.root.querySelector<HTMLCanvasElement>('[data-role="stage"]');
+  if (!canvas) return;
+  let session: PointerSession | undefined;
+  canvas.addEventListener('pointerdown', (event) => {
+    const point = canvasPoint(canvas, event);
+    session = { start: point, last: point, dragging: false, checkpointed: false };
+    canvas.setPointerCapture(event.pointerId);
+    if (state.mode === 'draw') return;
+    const frame = state.project.frames[state.currentFrame];
+    state.selectedId = frame ? shapeAtPoint(frame.shapes, point.x, point.y)?.id ?? '' : '';
+    renderEditor(state);
+  });
+  canvas.addEventListener('pointermove', (event) => movePointer(state, canvas, event, session));
+  canvas.addEventListener('pointerup', (event) => {
+    endPointer(state, canvas, event, session);
+    session = undefined;
+  });
+  canvas.addEventListener('pointercancel', () => {
+    session = undefined;
+    renderEditor(state);
+  });
+}
+
+function movePointer(state: EditorState, canvas: HTMLCanvasElement, event: PointerEvent, session?: PointerSession): void {
+  if (!session) return;
+  const point = canvasPoint(canvas, event);
+  session.dragging = Math.abs(point.x - session.start.x) > 0.5 || Math.abs(point.y - session.start.y) > 0.5;
+  if (state.mode === 'draw') {
+    renderDraft(state, session.start, point);
+  } else if (state.selectedId && session.dragging) {
+    if (!session.checkpointed) checkpoint(state);
+    session.checkpointed = true;
+    moveSelected(state, point.x - session.last.x, point.y - session.last.y);
+    renderEditor(state);
+  }
+  session.last = point;
+}
+
+function endPointer(state: EditorState, canvas: HTMLCanvasElement, event: PointerEvent, session?: PointerSession): void {
+  if (!session) return;
+  const point = canvasPoint(canvas, event);
+  if (state.mode === 'draw' && addDrawnShape(state, session.start, point)) setStatus(state, state.ui.statusShapeCreated);
+  else if (session.checkpointed) setStatus(state, state.ui.statusShapeUpdated);
+  renderEditor(state);
+}

package/src/tool/hitboxHurtboxAnimator/canvas-metrics.ts

@@ -0,0 +1,8 @@
+export function canvasPoint(canvas: HTMLCanvasElement, event: PointerEvent): { x: number; y: number } {
+  const rect = canvas.getBoundingClientRect();
+  const scale = Number(canvas.dataset.scale ?? 1);
+  return {
+    x: (event.clientX - rect.left) * (canvas.width / rect.width) / scale,
+    y: (event.clientY - rect.top) * (canvas.height / rect.height) / scale,
+  };
+}

package/src/tool/hitboxHurtboxAnimator/component.astro

@@ -0,0 +1,148 @@
+---
+import type { HitboxHurtboxAnimatorUI } from './ui';
+
+interface Props {
+  ui: HitboxHurtboxAnimatorUI;
+}
+
+const { ui } = Astro.props;
+---
+
+<div class="hha" data-hitbox-root tabindex="0">
+  <script is:inline type="application/json" data-role="locale-data" set:html={JSON.stringify(ui)}></script>
+
+  <div class="hha-intro">
+    <p>{ui.onboarding}</p>
+    <span>{ui.privacyNote}</span>
+  </div>
+
+  <section class="hha-load" data-role="dropzone">
+    <div>
+      <strong>{ui.loadSprite}</strong>
+      <p>{ui.loadHint}</p>
+    </div>
+    <label class="hha-button hha-button-primary">
+      {ui.chooseImages}
+      <input data-role="sprite-input" type="file" accept="image/png,image/webp" multiple />
+    </label>
+  </section>
+
+  <div class="hha-control-deck">
+    <fieldset>
+      <legend>{ui.slicingTitle}</legend>
+      <label>{ui.rowsLabel}<input data-role="rows" type="number" min="1" max="64" value="1" /></label>
+      <label>{ui.columnsLabel}<input data-role="columns" type="number" min="1" max="64" value="1" /></label>
+      <button type="button" class="hha-button" data-action="slice">{ui.applySlicing}</button>
+    </fieldset>
+    <fieldset>
+      <legend>{ui.playbackTitle}</legend>
+      <div class="hha-transport">
+        <button type="button" class="hha-icon-button is-previous" data-action="previous" aria-label={ui.previousFrame}><span></span></button>
+        <button type="button" class="hha-button hha-play" data-action="play">{ui.play}</button>
+        <button type="button" class="hha-icon-button is-next" data-action="next" aria-label={ui.nextFrame}><span></span></button>
+      </div>
+      <label class="hha-range">{ui.fpsLabel}<input data-preference="fps" type="range" min="1" max="30" value="12" /></label>
+      <label class="hha-check"><input data-preference="onionPrevious" type="checkbox" />{ui.onionPrevious}</label>
+      <label class="hha-check"><input data-preference="onionNext" type="checkbox" />{ui.onionNext}</label>
+    </fieldset>
+    <div class="hha-history">
+      <button type="button" class="hha-button" data-action="undo">{ui.undo}</button>
+      <button type="button" class="hha-button" data-action="redo">{ui.redo}</button>
+    </div>
+  </div>
+
+  <div class="hha-workbench">
+    <aside class="hha-layers">
+      <h2>{ui.layerTitle}</h2>
+      <div class="hha-mode-switch">
+        <button type="button" data-mode="draw">{ui.drawShape}</button>
+        <button type="button" data-mode="select">{ui.selectShape}</button>
+      </div>
+      <div class="hha-type-rack">
+        <button type="button" data-type="hitbox"><i></i>{ui.typeHitbox}</button>
+        <button type="button" data-type="hurtbox"><i></i>{ui.typeHurtbox}</button>
+        <button type="button" data-type="pushbox"><i></i>{ui.typePushbox}</button>
+        <button type="button" data-type="grabbox"><i></i>{ui.typeGrabbox}</button>
+        <button type="button" data-type="sensor"><i></i>{ui.typeSensor}</button>
+        <button type="button" data-type="custom"><i></i>{ui.typeCustom}</button>
+      </div>
+      <div class="hha-geometry">
+        <button type="button" data-geometry="rectangle"><span></span>{ui.shapeRectangle}</button>
+        <button type="button" data-geometry="circle"><span></span>{ui.shapeCircle}</button>
+      </div>
+    </aside>
+
+    <main class="hha-stage-column">
+      <div class="hha-stage-header">
+        <span>{ui.stageLabel}</span>
+        <div class="hha-badges">
+          <b data-role="frames-badge"></b>
+          <b data-role="shapes-badge"></b>
+          <b data-role="coverage-badge"></b>
+        </div>
+      </div>
+      <div class="hha-light-table">
+        <canvas data-role="stage" aria-label={ui.stageLabel}></canvas>
+        <div class="hha-empty-stage">
+          <span></span>
+          <p>{ui.emptyStage}</p>
+        </div>
+      </div>
+      <div class="hha-timeline-wrap">
+        <strong>{ui.timelineTitle}</strong>
+        <div class="hha-timeline" data-role="timeline"></div>
+      </div>
+    </main>
+
+    <aside class="hha-inspector">
+      <h2>{ui.inspectorTitle}</h2>
+      <p class="hha-no-selection" data-role="no-selection">{ui.noSelection}</p>
+      <div class="hha-fields" data-role="shape-fields" hidden>
+        <label class="hha-wide">{ui.nameLabel}<input data-field="name" type="text" /></label>
+        <label>{ui.xLabel}<input data-field="x" type="number" step="0.5" /></label>
+        <label>{ui.yLabel}<input data-field="y" type="number" step="0.5" /></label>
+        <label>{ui.widthLabel}<input data-field="width" type="number" min="1" step="0.5" /></label>
+        <label>{ui.heightLabel}<input data-field="height" type="number" min="1" step="0.5" /></label>
+        <label class="hha-wide" data-radius-row>{ui.radiusLabel}<input data-field="radius" type="number" min="0.5" step="0.5" /></label>
+        <button type="button" data-action="duplicate">{ui.duplicateShape}</button>
+        <button type="button" data-action="mirror">{ui.mirrorShape}</button>
+        <button type="button" class="hha-danger hha-wide" data-action="delete">{ui.deleteShape}</button>
+      </div>
+      <div class="hha-copy-actions">
+        <button type="button" data-action="copyPrevious">{ui.copyPrevious}</button>
+        <button type="button" data-action="copyAll">{ui.copyAll}</button>
+      </div>
+      <fieldset class="hha-pivot">
+        <legend>{ui.pivotTitle}</legend>
+        <label>{ui.pivotXLabel}<input data-field="pivotX" type="number" min="0" step="0.5" /></label>
+        <label>{ui.pivotYLabel}<input data-field="pivotY" type="number" min="0" step="0.5" /></label>
+      </fieldset>
+      <p class="hha-coordinate-note">{ui.coordinatesNote}</p>
+    </aside>
+  </div>
+
+  <section class="hha-export">
+    <div>
+      <strong>{ui.exportTitle}</strong>
+      <p>{ui.localOnlyDisclosure}</p>
+    </div>
+    <div>
+      <button type="button" class="hha-button hha-button-primary" data-action="exportJson">{ui.exportJson}</button>
+      <button type="button" class="hha-button" data-action="importJson">{ui.importJson}</button>
+      <button type="button" class="hha-button" data-action="contactSheet">{ui.exportContactSheet}</button>
+      <button type="button" class="hha-button hha-danger" data-action="reset">{ui.resetProject}</button>
+      <input data-role="project-input" type="file" accept="application/json,.json" aria-label={ui.importJson} />
+    </div>
+  </section>
+
+  <div class="hha-footer-line">
+    <p data-role="status" aria-live="polite"></p>
+    <p>{ui.limitationDisclosure}</p>
+  </div>
+</div>
+
+<script>
+  import { mountHitboxHurtboxAnimator } from './controller';
+
+  document.querySelectorAll<HTMLElement>('[data-hitbox-root]').forEach(mountHitboxHurtboxAnimator);
+</script>