ark-stronghold-protocol/docs/history/0.2.5.md

DESIGN §30 — 0.2.5

Part of DESIGN.md. This chapter records the changes after the 0.2.4 release.

30. After the 0.2.4 release

30.1 Official battlefield scenes (#532)

Report: the web board draws the metal theme for every battlefield, which looks unlike the official client; the reporter asked for the sand theme.

Findings (2026-10-11; evidence: the official hot-update lists and asset indexes, read from the CDN, and the scene bundles of version 26-04-13-12-31-42_e9b560):

• The official board is not assembled at run time. Every battlefield is a prebuilt scene bundle, shipped only while the season runs — §15 said otherwise from an off-season list and is corrected.
• Which art a battlefield uses is the dependency list of its scene bundle: the sand theme for act1 m01–m07 and act2 m02 / m04, map_lakegarden + map_syracuse_metro for act2 m01, map_kxmr + map_lm_center for act2 m03. The same in the 上半 version of 2025-11 and the 下半 versions of 2026-03 / 04. No battlefield uses the metal theme.
• The sand theme bundle holds no mesh because the models are baked into each scene ("Combined Mesh (root: scene)").
• A scene's three sub-graphics HIDDEN@1…3 are the left normal field, the right normal field and the boss field.

Change: tools/local-extract/scenes.py exports a battlefield's scene (meshes in board space, materials, key light, lightmap pages with the baked shadow mask in alpha, albedo textures) to public/assets/local/scene/<stageId>/; extract.py --only scene runs it, reading the scene bundles from the client, --scenes <dir> or .cache/official-scenes/*; tools/local-extract/fetch_scenes.py downloads the in-season bundles from the official CDN (md5-checked against that version's hot-update list). The 3D board draws a stage's scene when the local-art manifest lists it (board3d/load.js loadScenePack, scene.js setScenePack); the procedural board stays the fallback and still draws the devices, gates, field edges and terrain overlays. All eleven battlefields extract and draw.

No gameplay change: the scene is art under the same grid, camera and unit layer; golden results are untouched.

[ASSUMED] the light gains SCENE_LIGHT and the RGBM reading of the lightmap pages (§15); the approximations are listed there. Not done: the scene's normal / metallic / emission maps, map effects, sky box and post-processing; the tile graphics a level switches at run time (mire, tide) still use the remake's overlays.

Tests: test/render/board3d-scene.test.js (the scene table against data/stages.json, board-space conversion, chunk layout shared by scenes.py and load.js, sub-graphic groups, RGBM decode, the loader with a fake store, BoardScene with a stub renderer: scene on / areas / fallback, and the extracted files when present).