@ludra/core 0.4.0 → 0.7.0

package/src/validate.ts

@@ -1,5 +1,5 @@
 import { COMPONENT_NAMES, COMPONENTS, isComponentName, isFrameList, PARTICLE_FIELDS, type ComponentName, type FieldSpec } from "./components.ts";
-import { AUDIO_EXTENSIONS, EFFECT_FIELDS, IMAGE_EXTENSIONS, isSoundPreset, SOUND_PRESETS } from "./effects.ts";
+import { AUDIO_EXTENSIONS, EFFECT_FIELDS, FONT_EXTENSIONS, IMAGE_EXTENSIONS, isSoundPreset, SOUND_PRESETS } from "./effects.ts";
 import { EVENT_TYPES, type Diagnostic, type SceneDef } from "./types.ts";
 
 export interface ValidationResult {
@@ -44,6 +44,9 @@ export function validateScene(raw: unknown): ValidationResult {
           error("E_INVALID_WORLD", `world.${key}`, `world.${key} must be a non-negative number, got ${describe(value)}.`);
         }
       }
+      if (raw.world.seed !== undefined && (typeof raw.world.seed !== "number" || !Number.isFinite(raw.world.seed))) {
+        error("E_INVALID_WORLD", "world.seed", `world.seed must be a number, got ${describe(raw.world.seed)}.`);
+      }
       if (raw.world.background !== undefined && typeof raw.world.background !== "string") {
         error("E_INVALID_WORLD", "world.background", `world.background must be a CSS color string, got ${describe(raw.world.background)}.`);
       }
@@ -51,6 +54,8 @@ export function validateScene(raw: unknown): ValidationResult {
   }
 
   if (raw.effects !== undefined) validateEffects(raw.effects, error, warn);
+  if (raw.fonts !== undefined) validateFonts(raw.fonts, error);
+  if (raw.postfx !== undefined) validatePostFx(raw.postfx, error);
 
   if (!Array.isArray(raw.entities)) {
     error("E_NO_ENTITIES", "entities", 'A scene needs an "entities" array.', 'Add "entities": [].');
@@ -60,6 +65,7 @@ export function validateScene(raw: unknown): ValidationResult {
   const ids = new Map<string, number>();
   let hasPlayer = false;
   let hasDynamic = false;
+  const worldGravity = isObject(raw.world) && typeof raw.world.gravity === "number" ? raw.world.gravity : 1800;
   let hasSolid = false;
   let availableScore = 0;
   const goals: { path: string; label: string; requireScore: number }[] = [];
@@ -94,7 +100,7 @@ export function validateScene(raw: unknown): ValidationResult {
     for (const [name, value] of Object.entries(components)) {
       const componentPath = `${path}.components.${name}`;
       if (!isComponentName(name)) {
-        const suggestion = closest(name, COMPONENT_NAMES);
+        const suggestion = closestName(name, COMPONENT_NAMES);
         error(
           "E_UNKNOWN_COMPONENT",
           componentPath,
@@ -135,8 +141,34 @@ export function validateScene(raw: unknown): ValidationResult {
       );
     }
 
+    const script = isObject(components.script) ? components.script : undefined;
+    if (script && typeof script.src === "string" && !hasExtension(script.src, SCRIPT_EXTENSIONS)) {
+      error(
+        "E_INVALID_SCRIPT_PATH",
+        `${path}.components.script.src`,
+        `"${script.src}" on entity ${label} is not a script file.`,
+        'Use a path ending in .ts or .js, e.g. "scripts/chase.ts".',
+      );
+    }
+
     const body = isObject(components.body) ? components.body : undefined;
     const bodyType = body?.type ?? "static";
+    if ("topdown" in components && body && bodyType === "static") {
+      error(
+        "E_TOPDOWN_NEEDS_MOVING_BODY",
+        `${path}.components.body.type`,
+        `Entity ${label} has "topdown" but a static body, so it can never move.`,
+        'Use "type": "dynamic" to collide with walls, or "kinematic" to pass through them (a paddle or a ship).',
+      );
+    }
+    if ("topdown" in components && "platformer" in components) {
+      error(
+        "E_TWO_CONTROLLERS",
+        `${path}.components`,
+        `Entity ${label} has both "platformer" and "topdown", which would fight over its movement.`,
+        "Keep one: platformer for side-view games with gravity, topdown for top-down games, paddles and ships.",
+      );
+    }
     if ("platformer" in components && body && bodyType !== "dynamic") {
       error(
         "E_PLATFORMER_NEEDS_DYNAMIC_BODY",
@@ -168,8 +200,10 @@ export function validateScene(raw: unknown): ValidationResult {
     if (isObject(components.hazard) && components.hazard.stompable === true) availableScore += numberOr(components.hazard.score, 0);
     if (isObject(components.goal)) goals.push({ path: `${path}.components.goal.requireScore`, label, requireScore: numberOr(components.goal.requireScore, 0) });
 
-    if ("platformer" in components) hasPlayer = true;
-    if (body && bodyType === "dynamic") hasDynamic = true;
+    if ("platformer" in components || "topdown" in components) hasPlayer = true;
+    // Only bodies that gravity actually pulls down need something to stand on.
+    const falls = body && bodyType === "dynamic" && !("topdown" in components) && body.gravityScale !== 0;
+    if (falls && worldGravity !== 0) hasDynamic = true;
     if (body && bodyType !== "dynamic" && body.sensor !== true) hasSolid = true;
   });
 
@@ -192,7 +226,7 @@ export function validateScene(raw: unknown): ValidationResult {
     }
   }
   if (!hasPlayer) {
-    warn("W_NO_PLAYER", "entities", 'No entity has a "platformer" component, so nothing responds to input.');
+    warn("W_NO_PLAYER", "entities", 'No entity has a "platformer" or "topdown" component, so nothing responds to input (fine if scripts read input).');
   }
 
   return result();
@@ -229,7 +263,7 @@ function validateFields(
     if (ignore.includes(field)) continue;
     const spec = fields[field];
     if (!spec) {
-      const suggestion = closest(field, Object.keys(fields));
+      const suggestion = closestName(field, Object.keys(fields));
       warn(
         "W_UNKNOWN_FIELD",
         `${path}.${field}`,
@@ -250,6 +284,35 @@ function validateFields(
   }
 }
 
+function validateFonts(fonts: unknown, error: Report): void {
+  const example = 'Use "fonts": { "Orbitron": "google", "Pixel": "assets/pixel.woff2" }.';
+  if (!isObject(fonts)) return void error("E_FONTS_NOT_OBJECT", "fonts", '"fonts" must map font family names to "google" or a font file.', example);
+  for (const [family, src] of Object.entries(fonts)) {
+    const ok = typeof src === "string" && (src === "google" || FONT_EXTENSIONS.some((ext) => src.toLowerCase().endsWith(ext)));
+    if (!ok) {
+      error("E_INVALID_FONT", `fonts.${family}`, `fonts.${family} must be "google" or a font file (${FONT_EXTENSIONS.join(", ")}), got ${describe(src)}.`, example);
+    }
+  }
+}
+
+function validatePostFx(postfx: unknown, error: Report): void {
+  const example = 'Use "postfx": { "shader": "shaders/crt.frag", "uniforms": { "strength": 0.5 } }.';
+  if (!isObject(postfx)) return void error("E_POSTFX_NOT_OBJECT", "postfx", '"postfx" must be an object.', example);
+  if (typeof postfx.shader !== "string" || postfx.shader === "") {
+    error("E_POSTFX_SHADER", "postfx.shader", "postfx.shader must be the path of a GLSL fragment shader.", example);
+  }
+  if (postfx.uniforms !== undefined) {
+    if (!isObject(postfx.uniforms)) return void error("E_POSTFX_UNIFORMS", "postfx.uniforms", "postfx.uniforms must map names to numbers.", example);
+    for (const [name, value] of Object.entries(postfx.uniforms)) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || name.startsWith("u_")) {
+        error("E_POSTFX_UNIFORMS", `postfx.uniforms.${name}`, `"${name}" is not a usable uniform name. Use a GLSL identifier that doesn't start with "u_" (reserved for the engine).`);
+      } else if (typeof value !== "number" || !Number.isFinite(value)) {
+        error("E_POSTFX_UNIFORMS", `postfx.uniforms.${name}`, `postfx.uniforms.${name} must be a number, got ${describe(value)}.`);
+      }
+    }
+  }
+}
+
 function validateEffects(effects: unknown, error: Report, warn: Report): void {
   if (!isObject(effects)) {
     error("E_EFFECTS_NOT_OBJECT", "effects", '"effects" must map event names to effects.', 'Use "effects": { "collect": { "sound": "coin" } }.');
@@ -258,9 +321,16 @@ function validateEffects(effects: unknown, error: Report, warn: Report): void {
   for (const [event, effect] of Object.entries(effects)) {
     const path = `effects.${event}`;
     if (!(EVENT_TYPES as readonly string[]).includes(event)) {
-      const suggestion = closest(event, EVENT_TYPES);
-      error("E_UNKNOWN_EVENT", path, `There is no "${event}" event.`, `${suggestion ? `Did you mean "${suggestion}"? ` : ""}Events: ${EVENT_TYPES.join(", ")}.`);
-      continue;
+      // Any other name is a custom event that scripts fire with world.emit(). Flag likely typos of built-in ones.
+      const suggestion = closestName(event, EVENT_TYPES);
+      if (suggestion) {
+        warn(
+          "W_EVENT_LOOKS_LIKE_TYPO",
+          path,
+          `"${event}" is not a built-in event, so it only fires if a script calls world.emit("${event}").`,
+          `Did you mean "${suggestion}"? Built-in events: ${EVENT_TYPES.join(", ")}.`,
+        );
+      }
     }
     if (!isObject(effect)) {
       error("E_EFFECT_NOT_OBJECT", path, `effects.${event} must be an object.`, `Use { "sound": "blip", "particles": { "count": 8 } }.`);
@@ -268,7 +338,7 @@ function validateEffects(effects: unknown, error: Report, warn: Report): void {
     }
     validateFields(EFFECT_FIELDS, effect, path, `effects.${event}`, "", error, warn, ["particles"]);
     if (typeof effect.sound === "string" && effect.sound !== "" && !isSoundPreset(effect.sound) && !hasExtension(effect.sound, AUDIO_EXTENSIONS)) {
-      const suggestion = closest(effect.sound, SOUND_PRESETS);
+      const suggestion = closestName(effect.sound, SOUND_PRESETS);
       error(
         "E_INVALID_SOUND",
         `${path}.sound`,
@@ -286,6 +356,8 @@ function validateEffects(effects: unknown, error: Report, warn: Report): void {
   }
 }
 
+const SCRIPT_EXTENSIONS = [".ts", ".js"] as const;
+
 function hasExtension(path: string, extensions: readonly string[]): boolean {
   const lower = path.toLowerCase();
   return extensions.some((ext) => lower.endsWith(ext));
@@ -307,6 +379,8 @@ function checkField(spec: FieldSpec, value: unknown): string | undefined {
         : `must be one of ${spec.values.map((v) => `"${v}"`).join(", ")}, got ${describe(value)}.`;
     case "frames":
       return typeof value === "string" && isFrameList(value) ? undefined : `must be a frame list like "0", "1-4" or "0,2-3", got ${describe(value)}.`;
+    case "object":
+      return isObject(value) ? undefined : `must be an object like { "speed": 80 }, got ${describe(value)}.`;
   }
 }
 
@@ -326,7 +400,7 @@ function describe(value: unknown): string {
 }
 
 /** Returns the candidate within a small edit distance of `input`, if any. */
-function closest(input: string, candidates: readonly string[]): string | undefined {
+export function closestName(input: string, candidates: readonly string[]): string | undefined {
   let best: string | undefined;
   let bestDistance = Math.max(2, Math.floor(input.length / 3)) + 1;
   for (const candidate of candidates) {