add custom game data overrides

2026-11-01 16:18:38 +01:00
parent ea8e76a6b7
commit 1ccf4a760b
7 changed files with 459 additions and 1 deletions
@@ -0,0 +1,185 @@
+"use strict";
+// Local loader for values and new elements from ./custom/game.js.
+//
+// The file is mounted read-only at /app/custom and read whenever the backend or
+// game server starts. It is not part of the image, so edits need only a restart:
+//
+//   docker compose restart al-backend al-game
+//
+// The loader is deliberately fail-loud: a malformed custom file aborts startup
+// instead of silently producing a half-patched game. Unknown top-level keys,
+// unknown drop tables, references to missing items and new maps (their geometry
+// lives in MongoDB) are errors. New items/monsters are allowed when they use a
+// skin that already exists in design/dimensions.js.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const file = path.resolve(__dirname, "..", "custom", "game.js");
+
+// Sections that are deep-merged into the design globals. Maps are the exception
+// handled below: only existing maps can be changed.
+const sections = [
+	"items",
+	"monsters",
+	"npcs",
+	"maps",
+	"sets",
+	"craft",
+	"skills",
+	"conditions",
+	"classes",
+	"levels",
+	"upgrades",
+	"compounds",
+	"multipliers",
+	"titles",
+	"tokens",
+	"dismantle",
+];
+
+const allowed = new Set([...sections, "drops", "gold", "phrases", "apply"]);
+
+function fail(message) {
+	throw new Error("custom-game: " + message);
+}
+
+function is_plain(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function clone(value) {
+	return structuredClone(value);
+}
+
+function load() {
+	if (!fs.existsSync(file)) return null;
+	const resolved = require.resolve(file);
+	// Re-read on every call: a restart of the game server reloads the mounted file.
+	delete require.cache[resolved];
+	const custom = require(resolved);
+	if (!is_plain(custom)) fail(file + " must export an object");
+	return custom;
+}
+
+function merge(target, source, where) {
+	for (const key of Object.keys(source)) {
+		const value = source[key];
+		if (value === undefined) continue;
+		if (is_plain(value)) {
+			if (!is_plain(target[key])) target[key] = {};
+			merge(target[key], value, where + "." + key);
+		} else if (Array.isArray(value)) {
+			target[key] = clone(value);
+		} else if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+			fail(where + "." + key + " must be a plain value");
+		} else {
+			target[key] = value;
+		}
+	}
+}
+
+// A new element may only reuse an existing graphic, never introduce a new one.
+// Monsters are drawn from design/dimensions.js (`dimensions`); items and
+// condition icons are drawn from the sprite atlas (`positions`).
+function check_graphics(section, id, entry, game) {
+	const dimensions = is_plain(game.dimensions) ? game.dimensions : {};
+	const positions = is_plain(game.positions) ? game.positions : {};
+	const exists = (section === "monsters" ? dimensions : positions);
+	if (section === "items") {
+		if (typeof entry.skin !== "string") fail("items." + id + ": new items need a skin (see design/dimensions.js)");
+		if (!exists[entry.skin]) fail("items." + id + ": skin \"" + entry.skin + "\" does not exist in design/dimensions.js");
+	}
+	if (section === "monsters") {
+		const skin = typeof entry.skin === "string" ? entry.skin : id;
+		if (!exists[skin]) fail("monsters." + id + ": skin \"" + skin + "\" does not exist in design/dimensions.js");
+	}
+	if (section === "conditions" && entry.skin !== undefined && !exists[entry.skin]) {
+		fail("conditions." + id + ": skin \"" + entry.skin + "\" does not exist in design/dimensions.js");
+	}
+}
+
+function merge_drops(game, drops) {
+	if (!is_plain(drops)) fail("drops must be an object of map -> rows");
+	for (const map of Object.keys(drops)) {
+		const rows = drops[map];
+		if (!Array.isArray(rows)) fail("drops." + map + " must be an array");
+		if (!Array.isArray(game.drops.maps[map])) fail("drops." + map + ": unknown drop table (see design/drops.js)");
+		for (const row of rows) {
+			if (!Array.isArray(row) || row.length < 2) fail("drops." + map + ": each row is [chance, item]");
+			if (typeof row[0] !== "number" || row[0] < 0) fail("drops." + map + ": chance must be a non-negative number");
+			if (typeof row[1] !== "string") fail("drops." + map + ": item must be a string");
+			if (!is_plain(game.items[row[1]])) fail("drops." + map + ": unknown item \"" + row[1] + "\"");
+			game.drops.maps[map].push(clone(row));
+		}
+	}
+}
+
+function apply(game) {
+	const custom = load();
+	if (!custom) return;
+	if (!is_plain(game)) fail("internal: game data is missing");
+	for (const key of Object.keys(custom)) {
+		if (!allowed.has(key)) fail("unknown top-level key \"" + key + "\"");
+	}
+
+	const created = [];
+	for (const section of sections) {
+		const entries = custom[section];
+		if (entries === undefined) continue;
+		if (!is_plain(entries)) fail(section + " must be an object of id -> values");
+		if (!is_plain(game[section])) fail("internal: " + section + " data is missing");
+		for (const id of Object.keys(entries)) {
+			const patch = entries[id];
+			if (!is_plain(patch)) fail(section + "." + id + " must be an object");
+			if (section === "maps" && !is_plain(game.maps[id])) {
+				fail("maps." + id + ": a new map needs geometry in MongoDB; only existing maps can be changed");
+			}
+			const is_new = !is_plain(game[section][id]);
+			if (is_new) {
+				game[section][id] = {};
+				created.push(section + "." + id);
+			}
+			merge(game[section][id], patch, section + "." + id);
+			if (is_new) check_graphics(section, id, game[section][id], game);
+		}
+	}
+
+	if (custom.drops !== undefined) merge_drops(game, custom.drops);
+
+	if (custom.gold !== undefined) {
+		if (!is_plain(game.drops.gold)) fail("internal: drops.gold data is missing");
+		if (!is_plain(custom.gold)) fail("gold must be an object");
+		merge(game.drops.gold, custom.gold, "gold");
+	}
+
+	if (custom.apply !== undefined) {
+		if (typeof custom.apply !== "function") fail("apply must be a function");
+		custom.apply(game);
+	}
+
+	console.log("custom-game: loaded " + file + (created.length ? " (new: " + created.join(", ") + ")" : ""));
+}
+
+function validate_phrases(where, map) {
+	if (map === undefined) return {};
+	if (!is_plain(map)) fail(where + " must be an object of phrase id -> text");
+	for (const id of Object.keys(map)) {
+		if (typeof map[id] !== "string") fail(where + "." + id + " must be a string");
+	}
+	return map;
+}
+
+// Phrase overrides reach both the server-rendered pages and the browser bundle.
+// "*" applies to every language; a language entry takes precedence. This keeps
+// numbers in a tooltip correct in all languages unless translated per language.
+function phrases(language) {
+	const custom = load();
+	if (!custom || custom.phrases === undefined) return {};
+	if (!is_plain(custom.phrases)) fail("phrases must be an object of language -> phrase map");
+	const all = validate_phrases("phrases.*", custom.phrases["*"]);
+	const own = validate_phrases("phrases." + language, custom.phrases[language]);
+	return Object.assign({}, all, own);
+}
+
+module.exports = { apply: apply, phrases: phrases, file: file };
@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// Local patch: custom game values and elements from custom/game.js.
+//
+// The loader (docker/custom_game.js) itself needs no source changes, but the
+// game data is built inside eval() scope, so three small hooks are inserted at
+// image build time:
+//
+//   1. main.js and node/server.js call the loader after the seasonal flags are
+//      applied, so custom values win over the shipped design and over events.
+//   2. node/logic/encouragement.js reads the Lone Wolf rates from the condition
+//      definition instead of hardcoded 3s, so custom/game.js can tune them.
+//   3. languages/index.js merges custom phrase overrides into the catalogs, so
+//      tooltips such as the Lone Wolf explanation match tuned numbers.
+//
+// Every edit is idempotent and fails loudly if the upstream anchor is gone, so
+// an upstream update cannot silently drop the hooks.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const app = path.resolve(process.argv[2] || "/app");
+
+function fail(message) {
+	console.error("patch-custom-game: " + message);
+	process.exit(1);
+}
+
+function edit(file, marker, from, to, count) {
+	const full = path.join(app, file);
+	const source = fs.readFileSync(full, "utf8");
+	if (source.includes(marker)) {
+		console.log("patch-custom-game: " + file + " already patched");
+		return;
+	}
+	const occurrences = source.split(from).length - 1;
+	if (occurrences !== count) {
+		fail(file + ": expected " + count + " occurrence(s) of the anchor, found " + occurrences);
+	}
+	fs.writeFileSync(full, source.split(from).join(to));
+	console.log("patch-custom-game: patched " + file);
+}
+
+// 1a. Backend: design globals are module-scoped in main.js.
+edit(
+	"main.js",
+	'require("./docker/custom_game.js").apply',
+	`apply_event_flags({ maps: maps, items: items, monsters: monsters, drops: drops }, active_event_flags);
+
+// docs`,
+	`apply_event_flags({ maps: maps, items: items, monsters: monsters, drops: drops }, active_event_flags);
+
+// Local: values and new elements from the mounted custom/game.js.
+require("./docker/custom_game.js").apply({
+	items: items, monsters: monsters, npcs: npcs, maps: maps, sets: sets, craft: craft,
+	skills: skills, conditions: conditions, classes: classes, levels: levels, upgrades: upgrades,
+	compounds: compounds, multipliers: multipliers, titles: titles, tokens: tokens, dismantle: dismantle,
+	drops: drops, dimensions: dimensions, positions: positions,
+});
+
+// docs`,
+	1,
+);
+
+// 1b. Game server: the same globals are local to init_game() and reload_server().
+edit(
+	"node/server.js",
+	'require("../docker/custom_game.js").apply',
+	`\t\tvar season_data = { maps: maps, items: items, monsters: monsters, drops: drops };
+\t\tapply_event_flags(season_data, active_event_flags);
+\t\tseason_controls = { restore: season_data.event_restore || {}, end: end_event_flag };`,
+	`\t\tvar season_data = { maps: maps, items: items, monsters: monsters, drops: drops };
+\t\tapply_event_flags(season_data, active_event_flags);
+\t\t// Local: values and new elements from the mounted custom/game.js.
+\t\trequire("../docker/custom_game.js").apply({
+\t\t\titems: items, monsters: monsters, npcs: npcs, maps: maps, sets: sets, craft: craft,
+\t\t\tskills: skills, conditions: conditions, classes: classes, levels: levels, upgrades: upgrades,
+\t\t\tcompounds: compounds, multipliers: multipliers, titles: titles, tokens: tokens, dismantle: dismantle,
+\t\t\tdrops: drops, dimensions: dimensions, positions: positions,
+\t\t});
+\t\tseason_controls = { restore: season_data.event_restore || {}, end: end_event_flag };`,
+	2,
+);
+
+// 2. Lone Wolf rates become data-driven; the defaults keep upstream behaviour.
+edit(
+	"node/logic/encouragement.js",
+	"lonewolf_definition",
+	`\t\t} else if (!blocked && name === "encouragement_lonewolf" && lonewolf) {
+\t\t\tcondition = { gold_multiplier: 3, xp_multiplier: 3, luck_multiplier: 3 };`,
+	`\t\t} else if (!blocked && name === "encouragement_lonewolf" && lonewolf) {
+\t\t\t// Local: read the rates from design/conditions.js so custom/game.js can tune them.
+\t\t\tvar lonewolf_definition = (G.conditions && G.conditions[name]) || {};
+\t\t\tcondition = {
+\t\t\t\tgold_multiplier: lonewolf_definition.gold_multiplier === undefined ? 3 : lonewolf_definition.gold_multiplier,
+\t\t\t\txp_multiplier: lonewolf_definition.xp_multiplier === undefined ? 3 : lonewolf_definition.xp_multiplier,
+\t\t\t\tluck_multiplier: lonewolf_definition.luck_multiplier === undefined ? 3 : lonewolf_definition.luck_multiplier,
+\t\t\t};`,
+	1,
+);
+
+// 3a. Phrase lookup helper, next to the catalog loader.
+edit(
+	"languages/index.js",
+	"function custom_phrases(language)",
+	`function create_catalog_loader(directory, domains) {`,
+	`// Local: phrase overrides from the mounted custom/game.js.
+function custom_phrases(language) {
+	try {
+		return require("../docker/custom_game.js").phrases(language);
+	} catch (e) {
+		if (e && e.code === "MODULE_NOT_FOUND") return {};
+		throw e;
+	}
+}
+
+function create_catalog_loader(directory, domains) {`,
+	1,
+);
+
+// 3b. Apply the overrides after each language's files have been read.
+edit(
+	"languages/index.js",
+	"var custom = custom_phrases(language);",
+	`\t\t}
+\t\treturn result;
+\t}
+\treturn function catalog(language) {`,
+	`\t\t}
+\t\t// Local: custom names and explanations win over the shipped text.
+\t\tvar custom = custom_phrases(language);
+\t\tfor (var custom_id of Object.keys(custom)) result[custom_id] = custom[custom_id];
+\t\treturn result;
+\t}
+\treturn function catalog(language) {`,
+	1,
+);