@react-shimeji/core 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -223,6 +223,8 @@ interface ShimejiEngineOptions {
     workAreaClassName?: string;
     /** CSS class added to each generated mascot element. */
     mascotClassName?: string;
+    /** DOM elements, or a selector for elements, that mascots can use as platforms. */
+    platforms?: string | readonly HTMLElement[];
     /** Optional deterministic random-number source. */
     random?: () => number;
 }
@@ -269,7 +271,7 @@ interface MascotEnvironment {
             floor: EnvironmentEdge;
             /** Alias for the work-area top edge. */
             ceiling: EnvironmentEdge;
-            /** Inactive compatibility rectangle for page-element actions. */
+            /** Most relevant DOM platform for page-element actions. */
             activeIE: EnvironmentRectangle & {
                 visible: boolean;
             };
@@ -332,6 +334,7 @@ declare class ShimejiEngine {
     private nextMascotId;
     private destroyed;
     private initialized;
+    private platformSource;
     /** Creates and initializes an engine inside a host DOM element. */
     constructor(container: HTMLElement, options?: ShimejiEngineOptions);
     /** Starts the clock and global listeners. Calling this method more than once is harmless. */
@@ -352,12 +355,15 @@ declare class ShimejiEngine {
     getState(): MascotState[];
     /** Subscribes to a typed engine event and returns an unsubscribe function. */
     on<K extends keyof ShimejiEngineEventMap>(event: K, listener: ShimejiEventListener<K>): () => void;
+    /** Replaces the DOM elements (or selector) exposed to mascots as platforms. */
+    setPlatforms(platforms: string | readonly HTMLElement[]): void;
     /** Stops animation and timers, removes listeners and DOM, and revokes all object URLs. */
     destroy(): void;
     /** Returns whether this engine has completed permanent teardown. */
     isDestroyed(): boolean;
     private readonly onAnimationFrame;
     private renderAll;
+    private readFrameGeometry;
     private emitState;
     private listen;
     private assertAlive;
@@ -446,12 +452,21 @@ declare function isOnLeft(point: Point, rectangle: Rectangle, tolerance?: number
 /** Returns whether a point lies on the right edge of a rectangle. */
 declare function isOnRight(point: Point, rectangle: Rectangle, tolerance?: number): boolean;
 /** Returns whether an anchor satisfies an action's boundary requirement. */
-declare function isOnBorder(state: MascotState, bounds: Rectangle, border: "Floor" | "Wall" | "Ceiling" | undefined): boolean;
+declare function isOnBorder(state: MascotState, bounds: Rectangle, border: "Floor" | "Wall" | "Ceiling" | undefined, platform?: Rectangle): boolean;
 /** Advances ballistic motion and clamps the mascot to the work-area boundaries. */
-declare function applyGravity(state: MascotState, bounds: Rectangle, frameScale: number, gravity: number, resistanceX?: number, resistanceY?: number): boolean;
+declare function applyGravity(state: MascotState, bounds: Rectangle, frameScale: number, gravity: number, resistanceX?: number, resistanceY?: number, platform?: Rectangle): boolean;
 /** Moves a mascot toward a target without overshooting it. */
 declare function moveToward(state: MascotState, target: Point, speed: number, frameScale: number): boolean;
 
+/** A platform rectangle paired with the DOM element that produced it. */
+interface PlatformRectangle extends Rectangle {
+    element: HTMLElement;
+}
+/** Resolves a platform option into DOM elements, excluding engine-owned nodes. */
+declare function resolvePlatformElements(source: string | readonly HTMLElement[], document: Document, excludedRoot?: HTMLElement): HTMLElement[];
+/** Reads platform bounds once and converts viewport coordinates to work-area coordinates. */
+declare function readPlatformRectangles(elements: readonly HTMLElement[], workAreaRectangle: Pick<DOMRect, "left" | "top">): PlatformRectangle[];
+
 /** A resolved image and optional atlas crop for one sprite frame. */
 interface ResolvedSprite {
     /** Browser-loadable image URL. */
@@ -508,4 +523,4 @@ interface MascotCallbacks {
     error(error: Error): void;
 }
 
-export { type ActionDefinition, ActionExecutor, type ActionExecutorCallbacks, type ActionExecutorOptions, type ActionType, type AnimationDefinition, BehaviorController, type BehaviorDefinition, type BehaviorType, type BorderType, type CharacterMetadata, type CharacterSource, type CharacterSpec, type EnvironmentEdge, type EnvironmentRectangle, type IndividualSprite, type LegacyCharacterPack, type MascotCallbacks, type MascotDomHandle, type MascotEnvironment, type MascotState, type Point, type Pose, type Rectangle, type ResolvedSprite, ShimejiEngine, type ShimejiEngineEventMap, type ShimejiEngineOptions, type ShimejiEventListener, type SpawnOptions, type SpriteLease, SpriteManager, type SpriteMap, type SpriteRectangle, applyGravity, clamp, conditionsMatch, evaluateExpression, isIndividualSprite, isOnBorder, isOnBottom, isOnLeft, isOnRight, isOnTop, loadCharacter, moveToward, normalizeCharacterSpec, parseActionsXml, parseBehaviorsXml, selectWeighted };
+export { type ActionDefinition, ActionExecutor, type ActionExecutorCallbacks, type ActionExecutorOptions, type ActionType, type AnimationDefinition, BehaviorController, type BehaviorDefinition, type BehaviorType, type BorderType, type CharacterMetadata, type CharacterSource, type CharacterSpec, type EnvironmentEdge, type EnvironmentRectangle, type IndividualSprite, type LegacyCharacterPack, type MascotCallbacks, type MascotDomHandle, type MascotEnvironment, type MascotState, type PlatformRectangle, type Point, type Pose, type Rectangle, type ResolvedSprite, ShimejiEngine, type ShimejiEngineEventMap, type ShimejiEngineOptions, type ShimejiEventListener, type SpawnOptions, type SpriteLease, SpriteManager, type SpriteMap, type SpriteRectangle, applyGravity, clamp, conditionsMatch, evaluateExpression, isIndividualSprite, isOnBorder, isOnBottom, isOnLeft, isOnRight, isOnTop, loadCharacter, moveToward, normalizeCharacterSpec, parseActionsXml, parseBehaviorsXml, readPlatformRectangles, resolvePlatformElements, selectWeighted };

package/dist/index.d.ts

@@ -223,6 +223,8 @@ interface ShimejiEngineOptions {
     workAreaClassName?: string;
     /** CSS class added to each generated mascot element. */
     mascotClassName?: string;
+    /** DOM elements, or a selector for elements, that mascots can use as platforms. */
+    platforms?: string | readonly HTMLElement[];
     /** Optional deterministic random-number source. */
     random?: () => number;
 }
@@ -269,7 +271,7 @@ interface MascotEnvironment {
             floor: EnvironmentEdge;
             /** Alias for the work-area top edge. */
             ceiling: EnvironmentEdge;
-            /** Inactive compatibility rectangle for page-element actions. */
+            /** Most relevant DOM platform for page-element actions. */
             activeIE: EnvironmentRectangle & {
                 visible: boolean;
             };
@@ -332,6 +334,7 @@ declare class ShimejiEngine {
     private nextMascotId;
     private destroyed;
     private initialized;
+    private platformSource;
     /** Creates and initializes an engine inside a host DOM element. */
     constructor(container: HTMLElement, options?: ShimejiEngineOptions);
     /** Starts the clock and global listeners. Calling this method more than once is harmless. */
@@ -352,12 +355,15 @@ declare class ShimejiEngine {
     getState(): MascotState[];
     /** Subscribes to a typed engine event and returns an unsubscribe function. */
     on<K extends keyof ShimejiEngineEventMap>(event: K, listener: ShimejiEventListener<K>): () => void;
+    /** Replaces the DOM elements (or selector) exposed to mascots as platforms. */
+    setPlatforms(platforms: string | readonly HTMLElement[]): void;
     /** Stops animation and timers, removes listeners and DOM, and revokes all object URLs. */
     destroy(): void;
     /** Returns whether this engine has completed permanent teardown. */
     isDestroyed(): boolean;
     private readonly onAnimationFrame;
     private renderAll;
+    private readFrameGeometry;
     private emitState;
     private listen;
     private assertAlive;
@@ -446,12 +452,21 @@ declare function isOnLeft(point: Point, rectangle: Rectangle, tolerance?: number
 /** Returns whether a point lies on the right edge of a rectangle. */
 declare function isOnRight(point: Point, rectangle: Rectangle, tolerance?: number): boolean;
 /** Returns whether an anchor satisfies an action's boundary requirement. */
-declare function isOnBorder(state: MascotState, bounds: Rectangle, border: "Floor" | "Wall" | "Ceiling" | undefined): boolean;
+declare function isOnBorder(state: MascotState, bounds: Rectangle, border: "Floor" | "Wall" | "Ceiling" | undefined, platform?: Rectangle): boolean;
 /** Advances ballistic motion and clamps the mascot to the work-area boundaries. */
-declare function applyGravity(state: MascotState, bounds: Rectangle, frameScale: number, gravity: number, resistanceX?: number, resistanceY?: number): boolean;
+declare function applyGravity(state: MascotState, bounds: Rectangle, frameScale: number, gravity: number, resistanceX?: number, resistanceY?: number, platform?: Rectangle): boolean;
 /** Moves a mascot toward a target without overshooting it. */
 declare function moveToward(state: MascotState, target: Point, speed: number, frameScale: number): boolean;
 
+/** A platform rectangle paired with the DOM element that produced it. */
+interface PlatformRectangle extends Rectangle {
+    element: HTMLElement;
+}
+/** Resolves a platform option into DOM elements, excluding engine-owned nodes. */
+declare function resolvePlatformElements(source: string | readonly HTMLElement[], document: Document, excludedRoot?: HTMLElement): HTMLElement[];
+/** Reads platform bounds once and converts viewport coordinates to work-area coordinates. */
+declare function readPlatformRectangles(elements: readonly HTMLElement[], workAreaRectangle: Pick<DOMRect, "left" | "top">): PlatformRectangle[];
+
 /** A resolved image and optional atlas crop for one sprite frame. */
 interface ResolvedSprite {
     /** Browser-loadable image URL. */
@@ -508,4 +523,4 @@ interface MascotCallbacks {
     error(error: Error): void;
 }
 
-export { type ActionDefinition, ActionExecutor, type ActionExecutorCallbacks, type ActionExecutorOptions, type ActionType, type AnimationDefinition, BehaviorController, type BehaviorDefinition, type BehaviorType, type BorderType, type CharacterMetadata, type CharacterSource, type CharacterSpec, type EnvironmentEdge, type EnvironmentRectangle, type IndividualSprite, type LegacyCharacterPack, type MascotCallbacks, type MascotDomHandle, type MascotEnvironment, type MascotState, type Point, type Pose, type Rectangle, type ResolvedSprite, ShimejiEngine, type ShimejiEngineEventMap, type ShimejiEngineOptions, type ShimejiEventListener, type SpawnOptions, type SpriteLease, SpriteManager, type SpriteMap, type SpriteRectangle, applyGravity, clamp, conditionsMatch, evaluateExpression, isIndividualSprite, isOnBorder, isOnBottom, isOnLeft, isOnRight, isOnTop, loadCharacter, moveToward, normalizeCharacterSpec, parseActionsXml, parseBehaviorsXml, selectWeighted };
+export { type ActionDefinition, ActionExecutor, type ActionExecutorCallbacks, type ActionExecutorOptions, type ActionType, type AnimationDefinition, BehaviorController, type BehaviorDefinition, type BehaviorType, type BorderType, type CharacterMetadata, type CharacterSource, type CharacterSpec, type EnvironmentEdge, type EnvironmentRectangle, type IndividualSprite, type LegacyCharacterPack, type MascotCallbacks, type MascotDomHandle, type MascotEnvironment, type MascotState, type PlatformRectangle, type Point, type Pose, type Rectangle, type ResolvedSprite, ShimejiEngine, type ShimejiEngineEventMap, type ShimejiEngineOptions, type ShimejiEventListener, type SpawnOptions, type SpriteLease, SpriteManager, type SpriteMap, type SpriteRectangle, applyGravity, clamp, conditionsMatch, evaluateExpression, isIndividualSprite, isOnBorder, isOnBottom, isOnLeft, isOnRight, isOnTop, loadCharacter, moveToward, normalizeCharacterSpec, parseActionsXml, parseBehaviorsXml, readPlatformRectangles, resolvePlatformElements, selectWeighted };

package/dist/index.js

@@ -29,7 +29,10 @@ var DomManager = class {
   }
   /** Returns the current local work-area rectangle. */
   getBounds() {
-    const rectangle = this.workArea.getBoundingClientRect();
+    return this.getBoundsFromClientRectangle(this.workArea.getBoundingClientRect());
+  }
+  /** Converts a previously-read work-area client rectangle into local bounds. */
+  getBoundsFromClientRectangle(rectangle) {
     const width = rectangle.width || this.container.clientWidth || window.innerWidth;
     const height = rectangle.height || this.container.clientHeight || window.innerHeight;
     return { x: 0, y: 0, width, height };
@@ -597,7 +600,8 @@ var BehaviorController = class {
   isOnAnyBoundary(environment) {
     const anchor = environment.mascot.anchor;
     const area = environment.mascot.environment.workArea;
-    return area.topBorder.isOn(anchor) || area.leftBorder.isOn(anchor) || area.rightBorder.isOn(anchor) || area.bottomBorder.isOn(anchor);
+    const activeIE = environment.mascot.environment.activeIE;
+    return area.topBorder.isOn(anchor) || area.leftBorder.isOn(anchor) || area.rightBorder.isOn(anchor) || area.bottomBorder.isOn(anchor) || activeIE.visible && (activeIE.topBorder.isOn(anchor) || activeIE.leftBorder.isOn(anchor) || activeIE.rightBorder.isOn(anchor) || activeIE.bottomBorder.isOn(anchor));
   }
 };
 
@@ -617,17 +621,25 @@ function isOnLeft(point, rectangle, tolerance = 1) {
 function isOnRight(point, rectangle, tolerance = 1) {
   return point.y >= rectangle.y - tolerance && point.y <= rectangle.y + rectangle.height + tolerance && Math.abs(point.x - rectangle.x - rectangle.width) <= tolerance;
 }
-function isOnBorder(state, bounds, border) {
+function isOnBorder(state, bounds, border, platform) {
   if (!border) return true;
-  if (border === "Floor") return isOnBottom(state, bounds);
-  if (border === "Ceiling") return isOnTop(state, bounds);
-  return isOnLeft(state, bounds) || isOnRight(state, bounds);
+  if (border === "Floor") return isOnBottom(state, bounds) || platform !== void 0 && isOnTop(state, platform);
+  if (border === "Ceiling") return isOnTop(state, bounds) || platform !== void 0 && isOnBottom(state, platform);
+  return isOnLeft(state, bounds) || isOnRight(state, bounds) || platform !== void 0 && (isOnLeft(state, platform) || isOnRight(state, platform));
 }
-function applyGravity(state, bounds, frameScale, gravity, resistanceX = 0.05, resistanceY = 0.01) {
-  state.x = clamp(state.x + state.vx * frameScale, bounds.x, bounds.x + bounds.width);
-  state.y = clamp(state.y + state.vy * frameScale, bounds.y, bounds.y + bounds.height);
+function applyGravity(state, bounds, frameScale, gravity, resistanceX = 0.05, resistanceY = 0.01, platform) {
+  const previousY = state.y;
+  const nextX = clamp(state.x + state.vx * frameScale, bounds.x, bounds.x + bounds.width);
+  const nextY = clamp(state.y + state.vy * frameScale, bounds.y, bounds.y + bounds.height);
+  state.x = nextX;
+  state.y = nextY;
   state.vx *= Math.max(0, 1 - resistanceX * frameScale);
   state.vy = state.vy * Math.max(0, 1 - resistanceY * frameScale) + gravity * frameScale;
+  if (platform && nextY >= previousY && previousY <= platform.y && nextY >= platform.y && nextX >= platform.x && nextX <= platform.x + platform.width) {
+    state.y = platform.y;
+    state.vy = 0;
+    return true;
+  }
   if (state.y >= bounds.y + bounds.height) {
     state.y = bounds.y + bounds.height;
     state.vy = 0;
@@ -664,7 +676,8 @@ function evaluateAction(definition, environment) {
   const initialVx = numeric(definition.initialVx, scopedEnvironment);
   let lookRight = environment.mascot.lookRight;
   if (definition.borderType === "Wall") {
-    lookRight = environment.mascot.environment.workArea.rightBorder.isOn(environment.mascot.anchor);
+    const { activeIE, workArea } = environment.mascot.environment;
+    lookRight = workArea.rightBorder.isOn(environment.mascot.anchor) || activeIE.visible && activeIE.leftBorder.isOn(environment.mascot.anchor);
   } else if (definition.type === "Move" || definition.embedType === "Jump" || definition.embedType === "WalkWithIE") {
     if (targetX !== void 0) lookRight = targetX > environment.mascot.anchor.x;
   } else if (definition.embedType === "Fall" || definition.embedType === "FallWithIE") {
@@ -792,7 +805,15 @@ var LeafRuntime = class {
       case "Fall":
       case "FallWithIE":
       case "Thrown":
-        return applyGravity(this.state, bounds, frameScale, this.action.gravity ?? this.options.gravity, this.action.resistanceX, this.action.resistanceY);
+        return applyGravity(
+          this.state,
+          bounds,
+          frameScale,
+          this.action.gravity ?? this.options.gravity,
+          this.action.resistanceX,
+          this.action.resistanceY,
+          environment.mascot.environment.activeIE.visible ? environment.mascot.environment.activeIE : void 0
+        );
       case "Jump": {
         const target = { x: this.action.targetX ?? this.state.x, y: this.action.targetY ?? this.state.y };
         return moveToward(this.state, target, this.action.velocity ?? 20, frameScale);
@@ -873,7 +894,8 @@ var ActionExecutor = class {
   createRuntime(definition, environment, references) {
     if (definition.condition && !evaluateExpression(definition.condition, environment, false)) return new CompleteRuntime();
     const bounds = environment.mascot.environment.workArea;
-    if (!isOnBorder(this.state, bounds, definition.borderType)) return new CompleteRuntime();
+    const activeIE = environment.mascot.environment.activeIE;
+    if (!isOnBorder(this.state, bounds, definition.borderType, activeIE.visible ? activeIE : void 0)) return new CompleteRuntime();
     if (definition.type === "Reference") {
       if (!definition.name || references.has(definition.name)) return new CompleteRuntime();
       const referenced = this.spec.actions.find((action) => action.name === definition.name);
@@ -902,17 +924,26 @@ function environmentRectangle(bounds) {
   const top = bounds.y;
   const bottom = bounds.y + bounds.height;
   return {
-    ...bounds,
+    x: bounds.x,
+    y: bounds.y,
+    width: bounds.width,
+    height: bounds.height,
     left,
     right,
     top,
     bottom,
-    topBorder: edge((point) => Math.abs(point.y - top) <= 1),
-    leftBorder: edge((point) => Math.abs(point.x - left) <= 1),
-    rightBorder: edge((point) => Math.abs(point.x - right) <= 1),
-    bottomBorder: edge((point) => Math.abs(point.y - bottom) <= 1)
+    topBorder: edge((point) => isOnTop(point, bounds)),
+    leftBorder: edge((point) => isOnLeft(point, bounds)),
+    rightBorder: edge((point) => isOnRight(point, bounds)),
+    bottomBorder: edge((point) => isOnBottom(point, bounds))
   };
 }
+var PLATFORM_NEARBY_DISTANCE = 400;
+function distanceToRectangle(point, rectangle) {
+  const dx = Math.max(rectangle.x - point.x, 0, point.x - rectangle.x - rectangle.width);
+  const dy = Math.max(rectangle.y - point.y, 0, point.y - rectangle.y - rectangle.height);
+  return Math.hypot(dx, dy);
+}
 var Mascot = class {
   /** Creates a mascot and immediately installs its pointer handlers. */
   constructor(id, spec, dom, options, spawnOptions, callbacks) {
@@ -959,10 +990,13 @@ var Mascot = class {
   pointerId;
   pointerDown;
   lastPointer;
+  activePlatformElement;
+  platforms = [];
   /** Advances behavior, animation, physics, and rendering by one clock tick. */
-  tick(deltaMs, bounds) {
+  tick(deltaMs, bounds, platforms = []) {
     if (this.destroyed) return;
-    const environment = this.createEnvironment(bounds);
+    this.platforms = platforms;
+    const environment = this.createEnvironment(bounds, platforms);
     if (this.state.dragging) {
       this.dom.render(this.domHandle, this.spec, this.state);
       return;
@@ -978,12 +1012,20 @@ var Mascot = class {
           }
           if (!started) break;
         }
-        if (!this.actions.tick(deltaMs, environment, bounds)) break;
+        const wasOnPlatformTop = environment.mascot.environment.activeIE.visible && environment.mascot.environment.activeIE.topBorder.isOn(this.state);
+        const completed = this.actions.tick(deltaMs, environment, bounds);
+        if (wasOnPlatformTop && !platforms.some((platform) => isOnTop(this.state, platform))) {
+          this.actions.cancel();
+          this.currentBehavior = this.findFallBehavior();
+          if (this.currentBehavior) this.startBehavior(this.createEnvironment(bounds, platforms));
+          break;
+        }
+        if (!completed) break;
         if (this.destroyed) return;
-        this.currentBehavior = this.behavior.selectNext(this.createEnvironment(bounds));
-        if (!this.currentBehavior || !this.startBehavior(this.createEnvironment(bounds))) {
+        this.currentBehavior = this.behavior.selectNext(this.createEnvironment(bounds, platforms));
+        if (!this.currentBehavior || !this.startBehavior(this.createEnvironment(bounds, platforms))) {
           this.currentBehavior = this.findFallBehavior();
-          if (!this.currentBehavior || !this.startBehavior(this.createEnvironment(bounds))) break;
+          if (!this.currentBehavior || !this.startBehavior(this.createEnvironment(bounds, platforms))) break;
         }
         deltaMs = 0;
       }
@@ -1014,9 +1056,11 @@ var Mascot = class {
   findFallBehavior() {
     return this.behavior.force("Fall") ?? this.behavior.force("\u843D\u4E0B\u3059\u308B");
   }
-  createEnvironment(bounds) {
+  createEnvironment(bounds, platforms = this.platforms) {
     const workArea = environmentRectangle(bounds);
     const inactive = environmentRectangle({ x: -100, y: -100, width: 0, height: 0 });
+    const platform = this.selectActivePlatform(platforms);
+    const activeIE = platform ? { ...environmentRectangle(platform), visible: true } : { ...inactive, visible: false };
     return {
       gap: 0,
       maxCount: 999,
@@ -1030,11 +1074,30 @@ var Mascot = class {
           workArea,
           floor: workArea.bottomBorder,
           ceiling: workArea.topBorder,
-          activeIE: { ...inactive, visible: false }
+          activeIE
         }
       }
     };
   }
+  selectActivePlatform(platforms) {
+    if (platforms.length === 0) {
+      this.activePlatformElement = void 0;
+      return void 0;
+    }
+    const anchor = this.state;
+    const current = platforms.find((platform) => platform.element === this.activePlatformElement);
+    if (current && (isOnTop(anchor, current, 2) || isOnBottom(anchor, current, 2) || isOnLeft(anchor, current, 2) || isOnRight(anchor, current, 2))) return current;
+    if (this.state.vy >= 0) {
+      const landingPlatform = platforms.filter((platform) => anchor.x >= platform.x && anchor.x <= platform.x + platform.width && platform.y >= anchor.y - 1).sort((left, right) => left.y - right.y)[0];
+      if (landingPlatform) {
+        this.activePlatformElement = landingPlatform.element;
+        return landingPlatform;
+      }
+    }
+    const nearby = [...platforms].map((platform) => ({ platform, distance: distanceToRectangle(anchor, platform) })).filter(({ distance }) => distance <= PLATFORM_NEARBY_DISTANCE).sort((left, right) => left.distance - right.distance)[0]?.platform;
+    this.activePlatformElement = nearby?.element;
+    return nearby;
+  }
   installPointerHandlers() {
     const element = this.domHandle.element;
     const listen = (target, type, listener) => {
@@ -1085,6 +1148,40 @@ var Mascot = class {
   }
 };
 
+// src/platform.ts
+function resolvePlatformElements(source, document2, excludedRoot) {
+  let elements;
+  if (typeof source === "string") {
+    try {
+      elements = [...document2.querySelectorAll(source)];
+    } catch {
+      return [];
+    }
+  } else {
+    elements = source;
+  }
+  const HTMLElementConstructor = document2.defaultView?.HTMLElement;
+  if (!HTMLElementConstructor) return [];
+  return [...new Set(elements)].filter(
+    (element) => element instanceof HTMLElementConstructor && element.isConnected && (!excludedRoot || !excludedRoot.contains(element))
+  );
+}
+function readPlatformRectangles(elements, workAreaRectangle) {
+  const rectangles = [];
+  for (const element of elements) {
+    const rectangle = element.getBoundingClientRect();
+    if (rectangle.width <= 0 || rectangle.height <= 0) continue;
+    rectangles.push({
+      element,
+      x: rectangle.left - workAreaRectangle.left,
+      y: rectangle.top - workAreaRectangle.top,
+      width: rectangle.width,
+      height: rectangle.height
+    });
+  }
+  return rectangles;
+}
+
 // src/sprite.ts
 function dataUriToBlob(source) {
   const match = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(source);
@@ -1165,7 +1262,8 @@ var defaults = {
   gravity: 2,
   maxDeltaTime: 100,
   workAreaClassName: "",
-  mascotClassName: ""
+  mascotClassName: "",
+  platforms: []
 };
 var ShimejiEngine = class {
   /** Creates and initializes an engine inside a host DOM element. */
@@ -1173,6 +1271,7 @@ var ShimejiEngine = class {
     this.container = container;
     if (!container) throw new TypeError("ShimejiEngine requires a container element");
     this.options = { ...defaults, ...options, random: options.random };
+    this.platformSource = this.options.platforms;
     this.originalContainerPosition = container.style.position;
     this.adjustedContainerPosition = getComputedStyle(container).position === "static";
     if (this.adjustedContainerPosition) container.style.position = "relative";
@@ -1196,6 +1295,7 @@ var ShimejiEngine = class {
   nextMascotId = 1;
   destroyed = false;
   initialized = false;
+  platformSource;
   /** Starts the clock and global listeners. Calling this method more than once is harmless. */
   initialize() {
     this.assertAlive();
@@ -1237,12 +1337,12 @@ var ShimejiEngine = class {
     this.assertAlive();
     const spec = this.specs.get(characterId);
     if (!spec) throw new Error(`Character '${characterId}' is not registered`);
-    const bounds = this.dom.getBounds();
+    const { bounds, platforms } = this.readFrameGeometry();
     const random = this.options.random ?? Math.random;
     const spawnOptions = {
       ...position,
       x: position.x ?? bounds.x + random() * bounds.width,
-      y: position.y ?? bounds.y + random() * bounds.height
+      y: position.y ?? bounds.y
     };
     const id = `shimeji-${this.nextMascotId++}`;
     const mascot = new Mascot(id, spec, this.dom, this.options, spawnOptions, {
@@ -1258,7 +1358,7 @@ var ShimejiEngine = class {
       error: (error) => this.events.emit("error", error)
     });
     this.mascots.set(id, mascot);
-    mascot.tick(0, bounds);
+    mascot.tick(0, bounds, platforms);
     const state = mascot.snapshot();
     this.events.emit("spawn", state);
     this.emitState();
@@ -1290,6 +1390,11 @@ var ShimejiEngine = class {
     this.assertAlive();
     return this.events.on(event, listener);
   }
+  /** Replaces the DOM elements (or selector) exposed to mascots as platforms. */
+  setPlatforms(platforms) {
+    this.assertAlive();
+    this.platformSource = platforms;
+  }
   /** Stops animation and timers, removes listeners and DOM, and revokes all object URLs. */
   destroy() {
     if (this.destroyed) return;
@@ -1317,14 +1422,20 @@ var ShimejiEngine = class {
     const rawDelta = this.lastFrameTime === void 0 ? this.options.frameDuration : timestamp - this.lastFrameTime;
     this.lastFrameTime = timestamp;
     const delta = Math.max(0, Math.min(rawDelta, this.options.maxDeltaTime));
-    const bounds = this.dom.getBounds();
-    for (const mascot of [...this.mascots.values()]) mascot.tick(delta, bounds);
+    const { bounds, platforms } = this.readFrameGeometry();
+    for (const mascot of [...this.mascots.values()]) mascot.tick(delta, bounds, platforms);
     this.emitState();
     this.animationFrame = requestAnimationFrame(this.onAnimationFrame);
   };
   renderAll() {
-    const bounds = this.dom.getBounds();
-    for (const mascot of this.mascots.values()) mascot.tick(0, bounds);
+    const { bounds, platforms } = this.readFrameGeometry();
+    for (const mascot of this.mascots.values()) mascot.tick(0, bounds, platforms);
+  }
+  readFrameGeometry() {
+    const workAreaRectangle = this.dom.workArea.getBoundingClientRect();
+    const bounds = this.dom.getBoundsFromClientRectangle(workAreaRectangle);
+    const elements = resolvePlatformElements(this.platformSource, this.container.ownerDocument, this.dom.workArea);
+    return { bounds, platforms: readPlatformRectangles(elements, workAreaRectangle) };
   }
   emitState() {
     this.events.emit("statechange", this.getState());
@@ -1357,6 +1468,8 @@ export {
   normalizeCharacterSpec,
   parseActionsXml,
   parseBehaviorsXml,
+  readPlatformRectangles,
+  resolvePlatformElements,
   selectWeighted
 };
 //# sourceMappingURL=index.js.map