Studio scene pack contract for runtime SCENE binary payload

This commit is contained in:
2026-05-01 06:59:42 +01:00
parent 1182d3ae1f
commit 822e892c82
61 changed files with 120404 additions and 685 deletions
@@ -2,15 +2,22 @@ package p.packer.repositories;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import org.apache.commons.collections4.MapUtils;
import org.apache.commons.lang3.StringUtils;
import p.packer.messages.assets.ScenePackLayerRequest;
import p.packer.messages.assets.ScenePackRequest;
import p.packer.messages.assets.ScenePackTileRequest;
import p.packer.messages.assets.OutputFormatCatalog;
import p.packer.messages.diagnostics.PackerDiagnosticCategory;
import p.packer.messages.diagnostics.PackerDiagnosticSeverity;
import p.packer.models.*;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
@@ -26,11 +33,14 @@ public class PackerAssetWalker {
private static final Set<OutputFormatCatalog> SOUND_BANK_SUPPORTED_FORMATS = Set.of(
OutputFormatCatalog.SOUND_V1
);
private static final String SCENE_PACK_REQUEST_FILE = "scene-bank.pack-request.json";
private final ObjectMapper mapper;
private final PackerGlyphBankWalker glyphBankWalker;
private final PackerSoundBankWalker soundBankWalker;
public PackerAssetWalker(final ObjectMapper mapper) {
this.mapper = mapper;
this.glyphBankWalker = new PackerGlyphBankWalker(mapper);
this.soundBankWalker = new PackerSoundBankWalker(mapper);
}
@@ -101,7 +111,7 @@ public class PackerAssetWalker {
return new PackerWalkResult(walkResult.probeResults(), diagnostics);
}
case SCENE_BANK -> {
return new PackerWalkResult(List.of(), diagnostics);
return walkSceneBank(assetRoot, declaration, diagnostics);
}
case UNKNOWN -> {
diagnostics.add(new PackerDiagnostic(
@@ -116,6 +126,96 @@ public class PackerAssetWalker {
return PackerWalkResult.EMPTY;
}
private PackerWalkResult walkSceneBank(
Path assetRoot,
PackerAssetDeclaration declaration,
List<PackerDiagnostic> diagnostics) {
if (declaration.outputFormat() != OutputFormatCatalog.SCENE_TILED_V1) {
diagnostics.add(new PackerDiagnostic(
PackerDiagnosticSeverity.ERROR,
PackerDiagnosticCategory.STRUCTURAL,
"Unsupported output format for Scene Bank: " + declaration.outputFormat(),
assetRoot,
true));
return new PackerWalkResult(List.of(), diagnostics);
}
final Path requestPath = assetRoot.resolve(SCENE_PACK_REQUEST_FILE).toAbsolutePath().normalize();
if (!Files.isRegularFile(requestPath)) {
diagnostics.add(new PackerDiagnostic(
PackerDiagnosticSeverity.ERROR,
PackerDiagnosticCategory.STRUCTURAL,
"Accepted Scene Bank request artifact is missing: " + SCENE_PACK_REQUEST_FILE,
requestPath,
true));
return new PackerWalkResult(List.of(), diagnostics);
}
try {
final byte[] bytes = Files.readAllBytes(requestPath);
final ScenePackRequest request = parseScenePackRequest(bytes);
final PackerFileProbe probe = new PackerFileProbe(
requestPath,
"application/json",
bytes.length,
Math.max(0L, Files.getLastModifiedTime(requestPath).toMillis()),
bytes);
return new PackerWalkResult(
List.of(new PackerProbeResult(
probe,
Map.of("scenePackRequest", request),
List.of())),
diagnostics);
} catch (IOException | IllegalArgumentException exception) {
diagnostics.add(new PackerDiagnostic(
PackerDiagnosticSeverity.ERROR,
PackerDiagnosticCategory.STRUCTURAL,
"Unable to read accepted Scene Bank request artifact: " + exception.getMessage(),
requestPath,
true));
return new PackerWalkResult(List.of(), diagnostics);
}
}
private ScenePackRequest parseScenePackRequest(byte[] bytes) throws IOException {
final JsonNode root = mapper.readTree(bytes);
if (root == null || !root.isObject()) {
throw new IllegalArgumentException("request root must be a JSON object");
}
final String format = root.path("format").asText("SCENE/tilemap_v1").trim();
if (!"SCENE/tilemap_v1".equals(format)) {
throw new IllegalArgumentException("request format must be SCENE/tilemap_v1");
}
if (!(root.path("layers") instanceof ArrayNode layersNode) || layersNode.size() != 4) {
throw new IllegalArgumentException("request must contain exactly 4 layers");
}
final List<ScenePackLayerRequest> layers = new ArrayList<>();
for (JsonNode layerNode : layersNode) {
final int width = layerNode.path("width").asInt(0);
final int height = layerNode.path("height").asInt(0);
if (!(layerNode.path("tiles") instanceof ArrayNode tilesNode)) {
throw new IllegalArgumentException("each layer must contain a tiles array");
}
final List<ScenePackTileRequest> tiles = new ArrayList<>();
for (JsonNode tileNode : tilesNode) {
tiles.add(new ScenePackTileRequest(
tileNode.path("active").asBoolean(false),
tileNode.path("glyph_id").asInt(0),
tileNode.path("palette_id").asInt(0),
tileNode.path("flip_x").asBoolean(false),
tileNode.path("flip_y").asBoolean(false)));
}
layers.add(new ScenePackLayerRequest(
layerNode.path("active").asBoolean(false),
layerNode.path("glyph_asset_id").asInt(0),
layerNode.path("tile_size").asInt(0),
(float) layerNode.path("parallax_factor_x").asDouble(0.0d),
(float) layerNode.path("parallax_factor_y").asDouble(0.0d),
width,
height,
tiles));
}
return new ScenePackRequest(root.path("version").asInt(0), layers);
}
private RequirementBuildResult<PackerGlyphBankRequirements> buildGlyphBankRequirements(
final PackerAssetDeclaration declaration,
final Map<String, String> metadata) {
@@ -161,6 +161,9 @@ public final class PackerRuntimeAssetMaterializer {
if (materializationConfig.mode() != PackerWalkMode.PACKING) {
return true;
}
if (declaration.assetFamily() == p.packer.messages.assets.AssetFamilyCatalog.SCENE_BANK) {
return true;
}
if (declaration.artifacts().isEmpty()) {
return false;
}
@@ -40,6 +40,7 @@ import java.util.stream.Stream;
public final class FileSystemPackerWorkspaceService implements PackerWorkspaceService {
private static final int GLYPH_BANK_COLOR_KEY_RGB565 = 0xF81F;
private static final String SCENE_BANK_SUPPORT_FILE = "scene-bank.studio.json";
private static final String SCENE_PACK_REQUEST_FILE = "scene-bank.pack-request.json";
private final ObjectMapper mapper;
private final PackerWorkspaceFoundation workspaceFoundation;
@@ -699,8 +700,11 @@ public final class FileSystemPackerWorkspaceService implements PackerWorkspaceSe
"name", "Layer " + index,
"width", 16,
"height", 16,
"tilemap", "layer-" + index + ".tmx",
"tileset_asset_root", ""));
"tilemap", "scene.tmx",
"tileset_asset_root", "",
"parallax_factor_x", 1.0,
"parallax_factor_y", 1.0,
"default_palette_id", 0));
}
supportFile.put("layers", layers);
mapper.writerWithDefaultPrettyPrinter().writeValue(
@@ -883,7 +887,8 @@ public final class FileSystemPackerWorkspaceService implements PackerWorkspaceSe
if (declaration == null) {
return List.of();
}
if (declaration.assetFamily() == AssetFamilyCatalog.GLYPH_BANK) {
if (declaration.assetFamily() == AssetFamilyCatalog.GLYPH_BANK
|| declaration.assetFamily() == AssetFamilyCatalog.SCENE_BANK) {
return List.of();
}
return List.of(new PackerDiagnostic(
@@ -1054,10 +1059,14 @@ public final class FileSystemPackerWorkspaceService implements PackerWorkspaceSe
private PackedAsset packRuntimeAsset(PackerRuntimeAsset runtimeAsset) {
final PackerAssetDeclaration declaration = runtimeAsset.parsedDeclaration().declaration();
if (declaration == null || declaration.assetFamily() != AssetFamilyCatalog.GLYPH_BANK) {
if (declaration == null) {
throw new IllegalStateException("Unsupported pack output family for current implementation.");
}
return packGlyphBank(runtimeAsset, declaration);
return switch (declaration.assetFamily()) {
case GLYPH_BANK -> packGlyphBank(runtimeAsset, declaration);
case SCENE_BANK -> packSceneBank(runtimeAsset, declaration);
default -> throw new IllegalStateException("Unsupported pack output family for current implementation.");
};
}
private boolean isEffectivelyIncludedInPackSet(PackerRuntimeAsset runtimeAsset) {
@@ -1065,7 +1074,13 @@ public final class FileSystemPackerWorkspaceService implements PackerWorkspaceSe
return false;
}
final PackerAssetDeclaration declaration = runtimeAsset.parsedDeclaration().declaration();
return declaration == null || !declaration.artifacts().isEmpty();
if (declaration == null) {
return true;
}
if (declaration.assetFamily() == AssetFamilyCatalog.SCENE_BANK) {
return true;
}
return !declaration.artifacts().isEmpty();
}
private PackedAsset packGlyphBank(PackerRuntimeAsset runtimeAsset, PackerAssetDeclaration declaration) {
@@ -1076,6 +1091,7 @@ public final class FileSystemPackerWorkspaceService implements PackerWorkspaceSe
final byte[] sheetPixels = new byte[width * height];
final Map<String, PackerRuntimeWalkFile> selectedByPath = new LinkedHashMap<>();
runtimeAsset.walkProjection().buildCandidateFiles().forEach(file -> selectedByPath.put(file.relativePath(), file));
final Map<Integer, Integer> declaredPaletteIndexByRgb = declaredPaletteIndexByRgb(declaration);
declaration.artifacts().stream()
.sorted(Comparator.comparingInt(PackerAssetArtifactSelection::index))
@@ -1088,13 +1104,18 @@ public final class FileSystemPackerWorkspaceService implements PackerWorkspaceSe
if (!(tileValue instanceof PackerTileIndexedV1 tile)) {
throw new IllegalStateException("Selected tile artifact is missing normalized tile metadata: " + artifact.file());
}
final byte[] paletteIndices = remapTilePaletteIndices(
tile,
walkFile.metadata().get("palette"),
artifact.file(),
declaredPaletteIndexByRgb);
final int tileX = (artifact.index() % tilesPerRow) * tileSize;
final int tileY = (artifact.index() / tilesPerRow) * tileSize;
for (int localY = 0; localY < tile.height(); localY += 1) {
for (int localX = 0; localX < tile.width(); localX += 1) {
final int sourceOffset = localY * tile.width() + localX;
final int targetOffset = (tileY + localY) * width + (tileX + localX);
sheetPixels[targetOffset] = tile.paletteIndices()[sourceOffset];
sheetPixels[targetOffset] = paletteIndices[sourceOffset];
}
}
});
@@ -1135,6 +1156,109 @@ public final class FileSystemPackerWorkspaceService implements PackerWorkspaceSe
declaration.preloadEnabled());
}
private byte[] remapTilePaletteIndices(
PackerTileIndexedV1 tile,
Object paletteMetadata,
String artifactFile,
Map<Integer, Integer> declaredPaletteIndexByRgb) {
final int[] originalArgb8888 = originalPaletteColors(paletteMetadata);
if (originalArgb8888.length == 0) {
throw new IllegalStateException("Selected tile artifact is missing palette metadata required for palette remapping: " + artifactFile);
}
final byte[] remapped = Arrays.copyOf(tile.paletteIndices(), tile.paletteIndices().length);
for (int index = 0; index < remapped.length; index += 1) {
final int paletteIndex = Byte.toUnsignedInt(remapped[index]);
if (paletteIndex == 0) {
continue;
}
if (paletteIndex > originalArgb8888.length) {
throw new IllegalStateException("Tile palette index exceeds discovered palette size for artifact: " + artifactFile);
}
final int originalArgb = originalArgb8888[paletteIndex - 1];
final Integer materialIndex = declaredPaletteIndexByRgb.get(rgb24(originalArgb));
if (materialIndex == null || materialIndex < 1 || materialIndex > 15) {
throw new IllegalStateException("Unable to resolve canonical palette index for artifact color in " + artifactFile);
}
remapped[index] = (byte) (materialIndex & 0x0F);
}
return remapped;
}
private Map<Integer, Integer> declaredPaletteIndexByRgb(PackerAssetDeclaration declaration) {
final JsonNode palettesNode = declaration.outputPipelineMetadata().get("palettes");
if (!(palettesNode instanceof ArrayNode palettesArray) || palettesArray.isEmpty()) {
throw new IllegalStateException("Glyph packing requires at least one declared pipeline palette.");
}
final JsonNode paletteNode = palettesArray.get(0).path("palette").path("originalArgb8888");
if (!paletteNode.isArray() || paletteNode.isEmpty()) {
throw new IllegalStateException("Glyph packing requires originalArgb8888 entries in the declared pipeline palette.");
}
final LinkedHashMap<Integer, Integer> mapping = new LinkedHashMap<>();
for (int index = 0; index < paletteNode.size(); index += 1) {
final JsonNode colorNode = paletteNode.get(index);
if (!colorNode.canConvertToInt()) {
throw new IllegalStateException("Declared pipeline palette contains a non-integer originalArgb8888 entry.");
}
mapping.put(rgb24(colorNode.intValue()), index + 1);
}
return Map.copyOf(mapping);
}
private int[] originalPaletteColors(Object paletteMetadata) {
if (paletteMetadata instanceof PackerPaletteV1 palette) {
return palette.originalArgb8888();
}
if (!(paletteMetadata instanceof Map<?, ?> map)) {
return new int[0];
}
final Object colors = map.get("originalArgb8888");
if (!(colors instanceof List<?> list)) {
return new int[0];
}
final int[] values = new int[list.size()];
for (int index = 0; index < list.size(); index += 1) {
final Object color = list.get(index);
if (!(color instanceof Number number)) {
return new int[0];
}
values[index] = number.intValue();
}
return values;
}
private int rgb24(int argb) {
return argb & 0x00FFFFFF;
}
private PackedAsset packSceneBank(PackerRuntimeAsset runtimeAsset, PackerAssetDeclaration declaration) {
final ScenePackRequest request = runtimeAsset.walkProjection().buildCandidateFiles().stream()
.map(file -> file.metadata().get("scenePackRequest"))
.filter(ScenePackRequest.class::isInstance)
.map(ScenePackRequest.class::cast)
.findFirst()
.orElseThrow(() -> new IllegalStateException("Accepted Scene Bank request artifact is missing from the packing snapshot: " + SCENE_PACK_REQUEST_FILE));
final byte[] payload = encodeScenePackRequest(request);
final LinkedHashMap<String, Object> runtimeMetadata = new LinkedHashMap<>();
runtimeMetadata.put("version", request.version());
runtimeMetadata.put("layer_count", request.layers().size());
runtimeMetadata.put("codec", Map.of());
final LinkedHashMap<String, Object> toolingMetadata = new LinkedHashMap<>(runtimeMetadata);
final PackerRegistryEntry registryEntry = runtimeAsset.registryEntry()
.orElseThrow(() -> new IllegalStateException("Packed runtime asset must be registered"));
return new PackedAsset(
registryEntry.assetId(),
declaration.name(),
"SCENE",
"NONE",
payload,
sceneDecodedSize(request),
runtimeMetadata,
toolingMetadata,
declaration.preloadEnabled());
}
private int parseTileSize(String value) {
return switch (Objects.requireNonNullElse(value, "")) {
case "8x8" -> 8;
@@ -1192,6 +1316,67 @@ public final class FileSystemPackerWorkspaceService implements PackerWorkspaceSe
return palettesNode instanceof ArrayNode palettesArray ? palettesArray.size() : 0;
}
private byte[] encodeScenePackRequest(ScenePackRequest request) {
final ByteArrayOutputStream output = new ByteArrayOutputStream();
writeBytes(output, new byte[]{'S', 'C', 'N', 'E'});
writeShortLE(output, request.version());
writeShortLE(output, request.layers().size());
writeIntLE(output, 0);
for (ScenePackLayerRequest layer : request.layers()) {
writeByte(output, layer.active() ? 0b0000_0001 : 0);
writeIntLE(output, layer.glyphAssetId());
writeByte(output, layer.tileSize());
writeShortLE(output, 0);
writeFloatLE(output, layer.parallaxFactorX());
writeFloatLE(output, layer.parallaxFactorY());
writeIntLE(output, layer.width());
writeIntLE(output, layer.height());
writeIntLE(output, layer.width() * layer.height());
writeIntLE(output, 0);
for (ScenePackTileRequest tile : layer.tiles()) {
int flags = tile.active() ? 0b0000_0001 : 0;
if (tile.flipX()) {
flags |= 0b0000_0010;
}
if (tile.flipY()) {
flags |= 0b0000_0100;
}
writeByte(output, flags);
writeByte(output, tile.paletteId());
writeShortLE(output, tile.glyphId());
}
}
return output.toByteArray();
}
private int sceneDecodedSize(ScenePackRequest request) {
int decodedSize = 0;
for (ScenePackLayerRequest layer : request.layers()) {
decodedSize += 16 + (layer.tiles().size() * 8);
}
return decodedSize;
}
private void writeIntLE(ByteArrayOutputStream output, int value) {
writeBytes(output, ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(value).array());
}
private void writeShortLE(ByteArrayOutputStream output, int value) {
writeBytes(output, ByteBuffer.allocate(2).order(ByteOrder.LITTLE_ENDIAN).putShort((short) value).array());
}
private void writeFloatLE(ByteArrayOutputStream output, float value) {
writeBytes(output, ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putFloat(value).array());
}
private void writeByte(ByteArrayOutputStream output, int value) {
output.write(value & 0xFF);
}
private void writeBytes(ByteArrayOutputStream output, byte[] bytes) {
output.writeBytes(bytes);
}
private Map<String, Object> normalizeToolingPipelineMetadata(PackerAssetDeclaration declaration) {
return new LinkedHashMap<>(PackerReadMessageMapper.normalizeMetadata(declaration.outputPipelineMetadata()));
}