pixospritz-core 0.10.1 → 1.0.1

package/src/engine/utils/enums.js

@@ -0,0 +1,305 @@
+/*                                                 *\
+** ----------------------------------------------- **
+**          Calliope - Pixos Game Engine   	       **
+** ----------------------------------------------- **
+**  Copyright (c) 2020-2025 - Kyle Derby MacInnis  **
+**                                                 **
+**    Any unauthorized distribution or transfer    **
+**       of this work is strictly prohibited.      **
+**                                                 **
+**               All Rights Reserved.              **
+** ----------------------------------------------- **
+\*                                                 */
+import { Vector } from '@Engine/utils/math/vector.js';
+
+// Mouse event enumeration
+export const Mouse = {
+  DOWN: 1,
+  UP: 2,
+  MOVE: 3,
+};
+
+// Degrees to Radians
+function degToRad(degrees) {
+  return (degrees * Math.PI) / 180;
+}
+
+// Directions enumeration & methods
+export const Direction = {
+  None: 0, //0000
+  Right: 1, //0001
+  Up: 2, //0010
+  Left: 4, //0100
+  Down: 8, //1000
+  All: 15, //1111
+
+  fromOffset(dp) {
+    if (dp[0] > 0) return Direction.Right;
+    if (dp[0] < 0) return Direction.Left;
+    if (dp[1] > 0) return Direction.Down;
+    if (dp[1] < 0) return Direction.Up;
+    return 0;
+  },
+
+  toOffset(dir) {
+    switch (dir) {
+      case Direction.Right:
+        return [1, 0];
+      case Direction.Up:
+        return [0, -1];
+      case Direction.Left:
+        return [-1, 0];
+      case Direction.Down:
+        return [0, 1];
+    }
+    return [0, 0];
+  },
+
+  reverse(dir) {
+    switch (dir) {
+      case Direction.Right:
+        return Direction.Left;
+      case Direction.Up:
+        return Direction.Down;
+      case Direction.Left:
+        return Direction.Right;
+      case Direction.Down:
+        return Direction.Up;
+    }
+    return Direction.None;
+  },
+
+  rotate(dir, ccw = false) {
+    switch (dir) {
+      case Direction.Right:
+        return ccw ? Direction.Up : Direction.Down;
+      case Direction.Up:
+        return ccw ? Direction.Left : Direction.Right;
+      case Direction.Left:
+        return ccw ? Direction.Down : Direction.Up;
+      case Direction.Down:
+        return ccw ? Direction.Right : Direction.Left;
+    }
+    return Direction.None;
+  },
+
+  // determine which camera facing applies (seems to be working)
+  adjustCameraDirection(vec) {
+    switch (vec.z % 8) {
+      case 0:
+        return 'N';
+      case 1:
+      case -7:
+        return 'NW';
+      case 2:
+      case -6:
+        return 'W';
+      case 3:
+      case -5:
+        return 'SW';
+      case 4:
+      case -4:
+        return 'S';
+      case 5:
+      case -3:
+        return 'SE';
+      case 6:
+      case -2:
+        return 'E';
+      case 7:
+      case -1:
+        return 'NE';
+    }
+  },
+
+  // Get camera-relative movement direction
+  // Maps input directions (forward/backward/left/right) to world directions based on camera facing
+  // Forward always moves "into" the screen (away from camera), backward comes toward camera
+  // Left/right are perpendicular to the camera view
+  getCameraRelativeDirection(inputDir, cameraDir) {
+    const mappings = {
+      // Camera North: forward moves north (up in world), etc.
+      'N':  { forward: Direction.Up,    backward: Direction.Down,  left: Direction.Left,  right: Direction.Right },
+      // Camera NE: forward moves up-right diagonally
+      'NE': { forward: Direction.Up,    backward: Direction.Down,  left: Direction.Up,    right: Direction.Down },
+      // Camera East: forward moves right, left moves up
+      'E':  { forward: Direction.Right, backward: Direction.Left,  left: Direction.Up,    right: Direction.Down },
+      // Camera SE: forward moves right-down diagonally  
+      'SE': { forward: Direction.Right, backward: Direction.Left,  left: Direction.Up,    right: Direction.Down },
+      // Camera South: inverted from North
+      'S':  { forward: Direction.Down,  backward: Direction.Up,    left: Direction.Right, right: Direction.Left },
+      // Camera SW: forward moves left-down diagonally
+      'SW': { forward: Direction.Down,  backward: Direction.Up,    left: Direction.Right, right: Direction.Left },
+      // Camera West: forward moves left, right moves up
+      'W':  { forward: Direction.Left,  backward: Direction.Right, left: Direction.Down,  right: Direction.Up },
+      // Camera NW: forward moves up-left diagonally
+      'NW': { forward: Direction.Left,  backward: Direction.Right, left: Direction.Down,  right: Direction.Up }
+    };
+    
+    const mapping = mappings[cameraDir] || mappings['N'];
+    return mapping[inputDir] || Direction.None;
+  },
+
+  // sprite sequence facing (Needs work -- still not quite right)
+  spriteSequence(dir, camera = 'N') {
+    switch (camera) {
+      case 'N':
+        switch (dir) {
+          case Direction.Up:
+            return 'N';
+          case Direction.Right:
+            return 'E';
+          case Direction.Down:
+            return 'S';
+          case Direction.Left:
+            return 'W';
+        }
+      case 'E':
+        switch (dir) {
+          case Direction.Up:
+            return 'W';
+          case Direction.Right:
+            return 'N';
+          case Direction.Down:
+            return 'E';
+          case Direction.Left:
+            return 'S';
+        }
+      case 'S':
+        switch (dir) {
+          case Direction.Up:
+            return 'S';
+          case Direction.Right:
+            return 'W';
+          case Direction.Down:
+            return 'N';
+          case Direction.Left:
+            return 'E';
+        }
+      case 'W':
+        switch (dir) {
+          case Direction.Up:
+            return 'E';
+          case Direction.Right:
+            return 'S';
+          case Direction.Down:
+            return 'W';
+          case Direction.Left:
+            return 'N';
+        }
+      case 'NE':
+        switch (dir) {
+          case Direction.Up:
+            return 'NW';
+          case Direction.Right:
+            return 'SE';
+          case Direction.Down:
+            return 'NE';
+          case Direction.Left:
+            return 'SW';
+        }
+      case 'SE':
+        switch (dir) {
+          case Direction.Up:
+            return 'SW';
+          case Direction.Right:
+            return 'NW';
+          case Direction.Down:
+            return 'SE';
+          case Direction.Left:
+            return 'NE';
+        }
+      case 'SW':
+        switch (dir) {
+          case Direction.Up:
+            return 'NE';
+          case Direction.Right:
+            return 'SW';
+          case Direction.Down:
+            return 'NW';
+          case Direction.Left:
+            return 'SE';
+        }
+      case 'NW':
+        switch (dir) {
+          case Direction.Up:
+            return 'SE';
+          case Direction.Right:
+            return 'NE';
+          case Direction.Down:
+            return 'SW';
+          case Direction.Left:
+            return 'NW';
+        }
+    }
+
+    return 'S';
+  },
+
+  // adjust draw offset based on rotation position
+  drawOffset(vec, camera = 'N') {
+    // return vec;
+    // todo -- needs work
+    switch (camera) {
+      case 'NE':
+        return vec.cross(new Vector(Math.sin(degToRad(315)), 2 * Math.cos(degToRad(315)), 0));
+      case 'NW':
+        return vec.cross(new Vector(-2 * Math.sin(degToRad(315)), -Math.cos(degToRad(315)), 0));
+      case 'SE':
+        return vec.cross(new Vector(Math.sin(degToRad(225)), Math.cos(degToRad(225)), 0));
+      case 'SW':
+        return vec.cross(new Vector(Math.sin(degToRad(135)), Math.cos(degToRad(135)), 0));
+      case 'E':
+        return vec.cross(new Vector(Math.sin(degToRad(270)), Math.cos(degToRad(270)), 0));
+      case 'W':
+        return vec.cross(new Vector(Math.sin(degToRad(90)), Math.cos(degToRad(90)), 0));
+      case 'S':
+        return vec.cross(new Vector(Math.sin(degToRad(180)), Math.cos(degToRad(180)), 0));
+      case 'N':
+        return vec.cross(new Vector(Math.sin(degToRad(0)), Math.cos(degToRad(0)), 0));
+      default:
+        return vec;
+    }
+  },
+
+  // object sequence rotation (TODO)
+  objectSequence(dir) {
+    switch (dir) {
+      case Direction.Right:
+        return [0, 90, 0];
+      case Direction.Up:
+        return [0, 0, 0];
+      case Direction.Left:
+        return [0, -90, 0];
+      case Direction.Down:
+        return [0, 180, 0];
+    }
+    return [0, 0, 0];
+  },
+};
+
+export const isObject = (item) => {
+  return item && typeof item === 'object' && !Array.isArray(item);
+};
+
+export const mergeDeep = (target, ...sources) => {
+  if (!sources.length) return target;
+  const source = sources.shift();
+  if (isObject(target) && isObject(source)) {
+    for (const key in source) {
+      if (isObject(source[key])) {
+        if (!target[key])
+          Object.assign(target, {
+            [key]: {},
+          });
+        mergeDeep(target[key], source[key]);
+      } else {
+        Object.assign(target, {
+          [key]: source[key] && Array.isArray(source[key]) ? [].concat(target[key] ?? [], source[key]) : source[key],
+        });
+      }
+    }
+  }
+
+  return mergeDeep(target, ...sources);
+};

package/src/engine/utils/generator.js

@@ -0,0 +1,156 @@
+/*                                                 *\
+** ----------------------------------------------- **
+**          Calliope - Pixos Game Engine   	       **
+** ----------------------------------------------- **
+**  Copyright (c) 2020-2025 - Kyle Derby MacInnis  **
+**                                                 **
+**    Any unauthorized distribution or transfer    **
+**       of this work is strictly prohibited.      **
+**                                                 **
+**               All Rights Reserved.              **
+** ----------------------------------------------- **
+\*                                                 */
+
+import { store } from 'react-recollect';
+
+import { Vector } from '@Engine/utils/math/vector.js';
+import { Direction } from '@Engine/utils/enums.js';
+
+// Store Name
+export const STORE_NAME = 'garden-tome';
+
+// generate random map zone
+export async function generateZone(self, gender, storeName, cyoa) {
+  // load current spritz or play welcome
+  let tome = self.engine.store.get(storeName);
+
+  if (!tome) {
+    // Initialize the garden
+    tome = {
+      gender: gender,
+      position: new Vector(...[8, 3, 0]),
+      selected: -2,
+      rain: true,
+      snow: false,
+      spritz: [],
+      sprites: [],
+      objects: [],
+    };
+
+    // Load CYOA config
+    Object.assign(tome, cyoa);
+
+    self.engine.store.add(storeName, tome);
+
+    // Generate a collection of spritz programmably
+    // and append them to the spritz collection.
+
+    // self.randomlyGenerateSprites();
+    // self.randomlySprites();
+    await self.playCutScene('welcome');
+  } else {
+    // load Sprites
+    await Promise.all(
+      tome.sprites
+        .filter((x) => {
+          // Determine whether to load sprite or not
+          // base on the tome settings and cyoa
+
+          return x.id == tome.selected;
+        })
+        .map(self.loadSprite.bind(self))
+    );
+
+    // Load Objects
+    await Promise.all(
+      tome.objects
+        .filter((x) => {
+          // Determine whether to load object or not
+          // base on the tome settings and cyoa
+
+          return x.id == tome.selected;
+        })
+        .map(self.loadObject.bind(self))
+    );
+
+    // Load NPCs for the zone
+    await Promise.all(
+      tome.npcs
+        .filter((x) => {
+          // Determine whether to load NPC and decide what
+          // dialogue is base on the tome settings and cyoa
+
+          return x.id == tome.selected;
+        })
+        .map(async (trigger) => {
+          // run trigger
+        })
+    );
+
+    // Apply any Triggers & Setup New Spritz if needed
+    await Promise.all(
+      tome.triggers
+        .filter((x) => {
+          // Determine whether to load trigger
+          // base on the tome settings and cyoa
+
+          return x.id == tome.selected;
+        })
+        .map(async (trigger) => {
+          // run trigger
+        })
+    );
+
+    // Finally - Play appropriate spritz
+    await Promise.all(
+      tome.spritz
+        .filter((x) => {
+          return x.id == tome.selected;
+        })
+        .map(async (spritz) => {
+          await self.playCutScene(spritz.id, tome.spritz);
+        })
+    );
+
+    // run custom spritz
+    let spritz = [
+      {
+        id: 'new-space' + Math.random(),
+        actions: [
+          // manual actions
+          // Scripted Dialogue Action Controls directly on sprites
+          {
+            sprite: 'avatar',
+            action: 'dialogue',
+            args: [
+              [
+                'Welcome traveler... I see you are exploring. Good. Please continue to look',
+                'You have travelled into the number ' + (store.pixos && store.pixos[storeName] ? store.pixos[storeName].selected : -2) + ' room',
+              ],
+              false,
+              { autoclose: true },
+            ],
+            scope: self, // scoped to the zone
+          },
+        ],
+      },
+    ];
+    await self.playCutScene(spritz[0].id, spritz);
+  }
+}
+
+// load avatar
+export async function loadAvatar(zone, storeName) {
+  // randomly pick gender & store
+  let gender =
+    typeof store.pixos[storeName]?.gender !== 'undefined' ? store.pixos[storeName].gender : ['male', 'female'][Math.floor((2 * Math.random()) % 2)];
+  // Load avatar (Male or Female)
+  await zone.loadSprite.bind(self)({
+    id: 'avatar',
+    type: 'characters/' + gender,
+    gender: gender,
+    pos: typeof store.pixos[storeName]?.position !== 'undefined' ? store.pixos[storeName].position : new Vector(...[8, 8, zone.getHeight(8, 8)]),
+    facing: Direction.Down,
+  });
+  return gender;
+}

package/src/engine/utils/index.js

@@ -0,0 +1,21 @@
+import { Vector, Vector4 } from './math/vector.js';
+
+/**
+ * Clamps a value between a minimum and maximum value.
+ * @param {number} value - The value to clamp.
+ * @param {number} min - The minimum allowed value.
+ * @param {number} max - The maximum allowed value.
+ * @returns {number} The clamped value.
+ */
+export const clamp = (value, min, max) => {
+  return Math.max(min, Math.min(value, max));
+};
+
+/**
+ * Utility functions and common exports for the Pixos Game Engine.
+ */
+export default {
+  Vector,
+  Vector4,
+  clamp,
+};

package/src/engine/utils/loaders/ActionLoader.js

@@ -0,0 +1,77 @@
+/*                                                 *\
+** ----------------------------------------------- **
+**          Calliope - Pixos Game Engine   	       **
+** ----------------------------------------------- **
+**  Copyright (c) 2020-2025 - Kyle Derby MacInnis  **
+**                                                 **
+**    Any unauthorized distribution or transfer    **
+**       of this work is strictly prohibited.      **
+**                                                 **
+**               All Rights Reserved.              **
+** ----------------------------------------------- **
+\*                                                 */
+
+import { debug } from '../debug-logger.js';
+import Action from '@Engine/core/queue/action.js';
+
+// Helps Loads New Action Instance
+export class ActionLoader {
+  constructor(engine, type, args, sprite, callback) {
+    this.engine = engine;
+    this.type = type;
+    this.args = args;
+    this.sprite = sprite;
+    this.callback = callback;
+    this.instances = {};
+    this.definitions = [];
+    this.assets = {};
+
+    let time = new Date().getTime();
+    let id = sprite.id + '-' + type + '-' + time;
+    return this.load(
+      type,
+      async function (action) {
+        await action.onLoad(args);
+      },
+      function (action) {
+        action.configure(type, sprite, id, time, args);
+      }
+    );
+  }
+  // Load Internal Action
+  async load(type) {
+    debug('Loader', 'Loading Action: ' + type);
+
+    let afterLoad = arguments[1];
+    let runConfigure = arguments[2];
+    if (!this.instances[type]) {
+      this.instances[type] = [];
+    }
+    debug('Loader', {afterLoad, runConfigure})
+    // New Instance (assigns properties loaded by type)
+    let instance = new Action(this.type, this.sprite, this.callback);
+    const actionModule = await import('../../actions/' + type + '.js');
+    Object.assign(instance, actionModule.default);
+    instance.templateLoaded = true;
+    debug('Loader', 'Notifying in Action: ' + type);
+
+    // Notify existing
+    await Promise.all(
+      this.instances[type].map(async function (instance) {
+        debug('Loader', {instance});
+        if (instance.afterLoad) await instance.afterLoad(instance.instance);
+      })
+    );
+    // construct
+    if (runConfigure) runConfigure(instance);
+    // load
+    if (afterLoad) {
+      if (instance.templateLoaded) afterLoad(instance);
+      else this.instances[type].push({ instance, afterLoad });
+    }
+
+    debug('Loader', 'Ending load Action: ' + type);
+
+    return instance;
+  }
+}