import { collectRenderableRoots, sortRenderables, withRenderablePass } from "../rendering/renderable.js";
import { Entity } from "./entity.js";
import { SceneManager } from "./sceneManager.js";
import { Maths } from "../math/math.js";
import { validateAuthoredUI } from "../ui/authoredUi.js";
export const SCENE_SCHEMA_VERSION = 1;
export const SCENE_DATA_VERSION = "1.0.0";
export const RESOURCE_REFERENCE_ERROR_CODE = "RESOURCE_REFERENCE_INVALID";
const RESOURCE_TYPES = {
tileset: new Set(["tileset", "image", "texture", "resource", "asset"]),
sprite: new Set(["sprite", "image", "texture", "resource", "asset"]),
animation: new Set(["animation", "resource", "asset"]),
audio: new Set(["audio", "sound", "music", "resource", "asset"]),
prefab: new Set(["prefab", "scene", "resource", "asset"]),
tilemap: new Set(["tilemap", "map", "resource", "asset"])
};
const describeReference = (value) => {
if (value === undefined || value === null) return "<missing>";
if (typeof value === "string") return value.trim() || "<empty>";
if (typeof value !== "object") return String(value);
for (const key of ["id", "path", "uri", "key", "ref"]) {
if (typeof value[key] === "string" && value[key].trim()) return value[key];
}
return "<malformed>";
};
/**
* Error raised when a serialized resource reference cannot be used safely.
* The code and fields are stable so editor and runtime diagnostics can consume
* the same failure without parsing the human-readable message.
*/
export class ResourceReferenceError extends Error {
constructor(kind, value, sourceLocation, reason, expected = "a non-empty path, id, uri, or key") {
const reference = describeReference(value);
super(`[${RESOURCE_REFERENCE_ERROR_CODE}] Invalid ${kind} resource reference '${reference}' at ${sourceLocation}: ${reason}. Expected ${expected}.`);
this.name = "ResourceReferenceError";
this.code = RESOURCE_REFERENCE_ERROR_CODE;
this.referenceType = kind;
this.resourceType = kind;
this.reference = reference;
this.source = sourceLocation;
this.sourceLocation = sourceLocation;
this.location = sourceLocation;
this.reason = reason;
this.expected = expected;
}
}
/** Return the usable string target from a serialized reference. */
export function getResourceReferenceTarget(value, kind, sourceLocation = kind) {
assertResourceReference(value, kind, sourceLocation);
if (typeof value === "string") return value.trim();
for (const key of ["path", "uri", "id", "key", "ref"]) {
if (typeof value[key] === "string" && value[key].trim()) return value[key].trim();
}
return null;
}
/** Validate a serialized resource reference without checking the filesystem. */
export function assertResourceReference(value, kind, sourceLocation = kind) {
const types = RESOURCE_TYPES[kind] || new Set([kind, "resource", "asset"]);
if (value === undefined || value === null) {
throw new ResourceReferenceError(kind, value, sourceLocation, "missing reference");
}
if (typeof value === "string") {
if (value.trim()) return value.trim();
throw new ResourceReferenceError(kind, value, sourceLocation, "reference is empty");
}
if (typeof value !== "object" || Array.isArray(value)) {
throw new ResourceReferenceError(kind, value, sourceLocation, "reference must be a string or reference object");
}
const declaredType = value.type ?? value.resourceType ?? value.assetType ?? value.kind;
if (declaredType !== undefined &&
(typeof declaredType !== "string" || !types.has(declaredType.toLowerCase()))) {
throw new ResourceReferenceError(kind, value, sourceLocation,
`declared type '${String(declaredType)}' is incompatible`);
}
const targetKeys = ["path", "uri", "id", "key", "ref"];
const target = targetKeys.find(key => typeof value[key] === "string" && value[key].trim());
if (!target) {
throw new ResourceReferenceError(kind, value, sourceLocation, "reference object has no usable target");
}
return value[target].trim();
}
const isObject = value => value !== null && typeof value === "object" && !Array.isArray(value);
function validateComponentReferences(component, sourceLocation) {
if (!isObject(component) || typeof component.type !== "string") return;
const componentType = component.type.toLowerCase();
const props = component.props;
const propsLocation = `${sourceLocation}.props`;
if (!isObject(props)) {
if (["sprite", "sound", "soundpool", "audio", "tilemap", "animator", "animation"].includes(componentType)) {
throw new ResourceReferenceError(componentType, props, propsLocation, "component properties are missing");
}
return;
}
if (componentType === "sprite") {
assertResourceReference(props.path ?? props.texture ?? props.asset ?? props.reference,
"sprite", `${propsLocation}.path`);
} else if (componentType === "sound" || componentType === "soundpool" || componentType === "audio") {
assertResourceReference(props.src ?? props.path ?? props.audio ?? props.asset ?? props.reference,
"audio", `${propsLocation}.${props.src !== undefined ? "src" : "path"}`);
} else if (componentType === "tilemap") {
assertResourceReference(props.tileset ?? props.tilesetRef ?? props.asset,
"tileset", `${propsLocation}.tileset`);
} else if (componentType === "animation") {
assertResourceReference(props.path ?? props.animation ?? props.asset ?? props.reference,
"animation", `${propsLocation}.animation`);
} else if (componentType === "animator") {
const animations = props.animations;
if (Array.isArray(animations)) {
animations.forEach((animation, index) => assertResourceReference(animation, "animation",
`${propsLocation}.animations[${index}]`));
} else if (animations !== undefined) {
if (isObject(animations) && !("path" in animations || "uri" in animations || "id" in animations || "key" in animations || "ref" in animations)) {
Object.entries(animations).forEach(([name, animation]) => assertResourceReference(animation, "animation",
`${propsLocation}.animations.${name}`));
} else {
assertResourceReference(animations, "animation", `${propsLocation}.animations`);
}
}
if (props.currentAnimation !== undefined) {
assertResourceReference(props.currentAnimation, "animation", `${propsLocation}.currentAnimation`);
}
}
}
function validateEntityReferences(entity, sourceLocation) {
if (!isObject(entity)) return;
if (entity.prefab !== undefined) assertResourceReference(entity.prefab, "prefab", `${sourceLocation}.prefab`);
if (entity.prefabRef !== undefined) assertResourceReference(entity.prefabRef, "prefab", `${sourceLocation}.prefabRef`);
if (Array.isArray(entity.components)) {
entity.components.forEach((component, index) =>
validateComponentReferences(component, `${sourceLocation}.components[${index}]`));
}
if (Array.isArray(entity.children)) {
entity.children.forEach((child, index) => validateEntityReferences(child, `${sourceLocation}.children[${index}]`));
}
}
/** Validate resource references in a serialized scene before instantiation. */
export function validateSceneResourceReferences(data, sourceLocation = "scene") {
if (!isObject(data)) return data;
if (Array.isArray(data.layers)) {
data.layers.forEach((layer, layerIndex) => {
const layerLocation = `${sourceLocation}.layers[${layerIndex}]`;
if (!isObject(layer)) return;
if (layer.type === "tilemap") {
assertResourceReference(layer.src, "tilemap", `${layerLocation}.src`);
}
if (layer.prefab !== undefined) {
assertResourceReference(layer.prefab, "prefab", `${layerLocation}.prefab`);
}
if (Array.isArray(layer.entities)) {
layer.entities.forEach((entity, entityIndex) =>
validateEntityReferences(entity, `${layerLocation}.entities[${entityIndex}]`));
}
});
}
if (Array.isArray(data.entities)) {
data.entities.forEach((entity, index) => validateEntityReferences(entity, `${sourceLocation}.entities[${index}]`));
}
if (data.prefab !== undefined) assertResourceReference(data.prefab, "prefab", `${sourceLocation}.prefab`);
if (Array.isArray(data.prefabs)) {
data.prefabs.forEach((prefab, index) => assertResourceReference(prefab, "prefab", `${sourceLocation}.prefabs[${index}]`));
} else if (isObject(data.prefabs)) {
Object.entries(data.prefabs).forEach(([name, prefab]) =>
assertResourceReference(prefab, "prefab", `${sourceLocation}.prefabs.${name}`));
}
return data;
}
const cloneSerializable = (value, seen = new WeakSet()) => {
if (value === null || typeof value !== "object") return value;
if (seen.has(value)) return undefined;
seen.add(value);
if (Array.isArray(value)) return value.map(item => cloneSerializable(item, seen));
const result = {};
for (const [key, item] of Object.entries(value)) {
const cloned = cloneSerializable(item, seen);
if (cloned !== undefined) result[key] = cloned;
}
return result;
};
/**
* Scene is a container for entities. It is used to organize the game objects in the game.
* SceneManager is used to load and unload scenes. A scene can be used to only load specific entities.
* If any entity is not part of a scene, it will be loaded by default.
* @class Scene
* @extends Entity
* @property {number} id - Id of the scene. This is used to load the scene.
*/
export class Scene extends Entity {
static SCHEMA_VERSION = SCENE_SCHEMA_VERSION;
static DATA_VERSION = SCENE_DATA_VERSION;
/** Called when The scene is loaded */
OnSceneLoad = () => { };
/** Called when the scene is unloaded */
OnSceneUnload = () => { };
/** Called when the scene is loaded in additive mode */
OnSceneLoadAdditive = () => { };
/** Called when the scene is unloaded in additive mode */
OnSceneUnloadAdditive = () => { };
constructor(name) {
super(name);
this.id = SceneManager.getIdForNewScene();
this.ui = { version: 1, elements: [] };
// Runtime navigation grids are loaded from map resources and are not serialized.
this.navigationTilemaps = new Map();
SceneManager.addScene(this);
}
/** Get the runtime navigation grid loaded from a tilemap resource path. */
getNavigationTilemap(resourcePath) {
return this.navigationTilemaps.get(resourcePath) ?? null;
}
/** Serialize the scene graph using the versioned scene contract. */
serialize() {
return {
type: "scene",
version: SCENE_DATA_VERSION,
schemaVersion: SCENE_SCHEMA_VERSION,
id: this.id,
name: this.name,
camera: this.cameraSettings ? cloneSerializable(this.cameraSettings) : undefined,
...(this.ui?.elements?.length ? { ui: cloneSerializable(validateAuthoredUI(this.ui)) } : {}),
layers: [{
name: "Main",
type: "object_layer",
root: true,
entities: this.children.map(child => child.serialize())
}]
};
}
toJSON() {
return this.serialize();
}
Serialize() {
return this.serialize();
}
/** @private */
draw(ctx) {
ctx.save();
if (this.activeCamera) {
this.activeCamera.apply(ctx);
} else if (this.cameraSettings && this.cameraSettings.bounds) {
const x = this.cameraSettings.bounds.x || 0;
const y = this.cameraSettings.bounds.y || 0;
const px = Maths.MeterToPixel(x);
const py = Maths.MeterToPixel(y);
ctx.translate(-px, -py);
}
withRenderablePass(ctx, () => {
sortRenderables(collectRenderableRoots(this))
.forEach(renderable => renderable.draw(ctx));
});
const camera = this.activeCamera;
const fadeAlpha = camera ? Math.max(0, Math.min(1, camera.fadeAlpha || 0)) : 0;
if (fadeAlpha > 0) {
const zoom = camera.zoom || 1;
ctx.save();
ctx.globalAlpha *= fadeAlpha;
ctx.fillStyle = "#000";
ctx.fillRect(camera.x, camera.y, camera.viewWidth / zoom, camera.viewHeight / zoom);
ctx.restore();
}
ctx.restore();
}
}