pixospritz-specs 1.0.1

package/math/matrix.spec.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://pixospritz.dev/schemas/matrix.spec.json",
+  "title": "Matrix Specification",
+  "description": "Shared matrix math specifications for JS and C engines",
+  
+  "definitions": {
+    "Matrix4": {
+      "description": "4x4 transformation matrix in column-major order (WebGL/OpenGL compatible)",
+      "type": "object",
+      "properties": {
+        "data": {
+          "type": "array",
+          "items": { "type": "number" },
+          "minItems": 16,
+          "maxItems": 16,
+          "description": "16 floats in column-major order: [m00, m10, m20, m30, m01, m11, m21, m31, ...]"
+        }
+      },
+      "required": ["data"]
+    },
+    
+    "Matrix3": {
+      "description": "3x3 matrix for rotations and normals",
+      "type": "object",
+      "properties": {
+        "data": {
+          "type": "array",
+          "items": { "type": "number" },
+          "minItems": 9,
+          "maxItems": 9
+        }
+      },
+      "required": ["data"]
+    }
+  },
+  
+  "operations": {
+    "Matrix4": {
+      "identity": {
+        "signature": "() -> Matrix4",
+        "description": "Create identity matrix",
+        "result": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+        "implementation": {
+          "js": "new Float32Array([1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1])",
+          "c": "mat4_identity()"
+        }
+      },
+      "multiply": {
+        "signature": "(a: Matrix4, b: Matrix4) -> Matrix4",
+        "description": "Matrix multiplication (a * b)",
+        "implementation": {
+          "js": "mat4_multiply(a, b)",
+          "c": "mat4_multiply(a, b)"
+        }
+      },
+      "translate": {
+        "signature": "(m: Matrix4, v: Vector3) -> Matrix4",
+        "description": "Apply translation",
+        "implementation": {
+          "js": "mat4_translate(m, v.x, v.y, v.z)",
+          "c": "mat4_translate(m, v.x, v.y, v.z)"
+        }
+      },
+      "rotate": {
+        "signature": "(m: Matrix4, angle: number, axis: Vector3) -> Matrix4",
+        "description": "Apply rotation around axis (angle in radians)",
+        "implementation": {
+          "js": "mat4_rotate(m, angle, axis.x, axis.y, axis.z)",
+          "c": "mat4_rotate(m, angle, axis.x, axis.y, axis.z)"
+        }
+      },
+      "rotateX": {
+        "signature": "(m: Matrix4, angle: number) -> Matrix4",
+        "description": "Rotate around X axis",
+        "implementation": {
+          "js": "mat4_rotateX(m, angle)",
+          "c": "mat4_rotate_x(m, angle)"
+        }
+      },
+      "rotateY": {
+        "signature": "(m: Matrix4, angle: number) -> Matrix4",
+        "description": "Rotate around Y axis",
+        "implementation": {
+          "js": "mat4_rotateY(m, angle)",
+          "c": "mat4_rotate_y(m, angle)"
+        }
+      },
+      "rotateZ": {
+        "signature": "(m: Matrix4, angle: number) -> Matrix4",
+        "description": "Rotate around Z axis",
+        "implementation": {
+          "js": "mat4_rotateZ(m, angle)",
+          "c": "mat4_rotate_z(m, angle)"
+        }
+      },
+      "scale": {
+        "signature": "(m: Matrix4, v: Vector3) -> Matrix4",
+        "description": "Apply scaling",
+        "implementation": {
+          "js": "mat4_scale(m, v.x, v.y, v.z)",
+          "c": "mat4_scale(m, v.x, v.y, v.z)"
+        }
+      },
+      "perspective": {
+        "signature": "(fov: number, aspect: number, near: number, far: number) -> Matrix4",
+        "description": "Create perspective projection matrix (fov in radians)",
+        "implementation": {
+          "js": "mat4_perspective(fov, aspect, near, far)",
+          "c": "mat4_perspective(fov, aspect, near, far)"
+        },
+        "notes": "fov is vertical field of view in radians"
+      },
+      "orthographic": {
+        "signature": "(left: number, right: number, bottom: number, top: number, near: number, far: number) -> Matrix4",
+        "description": "Create orthographic projection matrix",
+        "implementation": {
+          "js": "mat4_ortho(left, right, bottom, top, near, far)",
+          "c": "mat4_ortho(left, right, bottom, top, near, far)"
+        }
+      },
+      "lookAt": {
+        "signature": "(eye: Vector3, target: Vector3, up: Vector3) -> Matrix4",
+        "description": "Create view matrix looking from eye to target",
+        "implementation": {
+          "js": "mat4_lookAt(eye, target, up)",
+          "c": "mat4_look_at(eye, target, up)"
+        }
+      },
+      "invert": {
+        "signature": "(m: Matrix4) -> Matrix4",
+        "description": "Compute inverse matrix",
+        "implementation": {
+          "js": "mat4_invert(m)",
+          "c": "mat4_invert(m)"
+        }
+      },
+      "transpose": {
+        "signature": "(m: Matrix4) -> Matrix4",
+        "description": "Transpose matrix",
+        "implementation": {
+          "js": "mat4_transpose(m)",
+          "c": "mat4_transpose(m)"
+        }
+      }
+    }
+  },
+  
+  "layout": {
+    "description": "Column-major order for WebGL/OpenGL compatibility",
+    "indexMapping": {
+      "m00": 0, "m10": 1, "m20": 2, "m30": 3,
+      "m01": 4, "m11": 5, "m21": 6, "m31": 7,
+      "m02": 8, "m12": 9, "m22": 10, "m32": 11,
+      "m03": 12, "m13": 13, "m23": 14, "m33": 15
+    },
+    "translationIndices": [12, 13, 14],
+    "scaleIndices": [0, 5, 10]
+  }
+}

package/math/vector.spec.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://pixospritz.dev/schemas/vector.spec.json",
+  "title": "Vector Specification",
+  "description": "Shared vector math specifications for JS and C engines",
+  
+  "definitions": {
+    "Vector2": {
+      "description": "2D vector/coordinate",
+      "type": "object",
+      "properties": {
+        "x": { "type": "number", "default": 0 },
+        "y": { "type": "number", "default": 0 }
+      },
+      "required": ["x", "y"]
+    },
+    
+    "Vector3": {
+      "description": "3D vector",
+      "type": "object",
+      "properties": {
+        "x": { "type": "number", "default": 0 },
+        "y": { "type": "number", "default": 0 },
+        "z": { "type": "number", "default": 0 }
+      },
+      "required": ["x", "y", "z"]
+    },
+    
+    "Vector4": {
+      "description": "4D vector (homogeneous coordinates)",
+      "type": "object",
+      "properties": {
+        "x": { "type": "number", "default": 0 },
+        "y": { "type": "number", "default": 0 },
+        "z": { "type": "number", "default": 0 },
+        "w": { "type": "number", "default": 1 }
+      },
+      "required": ["x", "y", "z", "w"]
+    }
+  },
+  
+  "operations": {
+    "Vector3": {
+      "add": {
+        "signature": "(a: Vector3, b: Vector3) -> Vector3",
+        "description": "Component-wise addition",
+        "implementation": {
+          "js": "{ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z }",
+          "c": "vec3_add(a, b)"
+        }
+      },
+      "sub": {
+        "signature": "(a: Vector3, b: Vector3) -> Vector3",
+        "description": "Component-wise subtraction",
+        "implementation": {
+          "js": "{ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z }",
+          "c": "vec3_sub(a, b)"
+        }
+      },
+      "scale": {
+        "signature": "(v: Vector3, s: number) -> Vector3",
+        "description": "Scalar multiplication",
+        "implementation": {
+          "js": "{ x: v.x * s, y: v.y * s, z: v.z * s }",
+          "c": "vec3_scale(v, s)"
+        }
+      },
+      "dot": {
+        "signature": "(a: Vector3, b: Vector3) -> number",
+        "description": "Dot product",
+        "implementation": {
+          "js": "a.x * b.x + a.y * b.y + a.z * b.z",
+          "c": "vec3_dot(a, b)"
+        }
+      },
+      "cross": {
+        "signature": "(a: Vector3, b: Vector3) -> Vector3",
+        "description": "Cross product",
+        "implementation": {
+          "js": "{ x: a.y * b.z - a.z * b.y, y: a.z * b.x - a.x * b.z, z: a.x * b.y - a.y * b.x }",
+          "c": "vec3_cross(a, b)"
+        }
+      },
+      "length": {
+        "signature": "(v: Vector3) -> number",
+        "description": "Vector magnitude",
+        "implementation": {
+          "js": "Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z)",
+          "c": "vec3_length(v)"
+        }
+      },
+      "normalize": {
+        "signature": "(v: Vector3) -> Vector3",
+        "description": "Unit vector",
+        "implementation": {
+          "js": "const len = length(v); return len > 0 ? scale(v, 1/len) : { x: 0, y: 0, z: 0 }",
+          "c": "vec3_normalize(v)"
+        }
+      },
+      "distance": {
+        "signature": "(a: Vector3, b: Vector3) -> number",
+        "description": "Euclidean distance between two points",
+        "implementation": {
+          "js": "length(sub(b, a))",
+          "c": "vec3_distance(a, b)"
+        }
+      },
+      "lerp": {
+        "signature": "(a: Vector3, b: Vector3, t: number) -> Vector3",
+        "description": "Linear interpolation",
+        "implementation": {
+          "js": "{ x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t, z: a.z + (b.z - a.z) * t }",
+          "c": "vec3_lerp(a, b, t)"
+        }
+      },
+      "negate": {
+        "signature": "(v: Vector3) -> Vector3",
+        "description": "Negate all components",
+        "implementation": {
+          "js": "{ x: -v.x, y: -v.y, z: -v.z }",
+          "c": "vec3_negate(v)"
+        }
+      }
+    }
+  },
+  
+  "constants": {
+    "ZERO": { "x": 0, "y": 0, "z": 0 },
+    "ONE": { "x": 1, "y": 1, "z": 1 },
+    "UP": { "x": 0, "y": 1, "z": 0 },
+    "DOWN": { "x": 0, "y": -1, "z": 0 },
+    "LEFT": { "x": -1, "y": 0, "z": 0 },
+    "RIGHT": { "x": 1, "y": 0, "z": 0 },
+    "FORWARD": { "x": 0, "y": 0, "z": -1 },
+    "BACK": { "x": 0, "y": 0, "z": 1 }
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "pixospritz-specs",
+  "version": "1.0.1",
+  "description": "Shared specifications, schemas, and constants for PixoSpritz engines",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./math/*": "./math/*.json",
+    "./formats/*": "./formats/*.json",
+    "./constants/*": "./constants/*.json",
+    "./shaders/*": "./shaders/*"
+  },
+  "bin": {
+    "generate-c-headers": "./generate-c-headers.cjs"
+  },
+  "scripts": {
+    "generate": "node generate-c-headers.cjs",
+    "generate:core-c": "node generate-c-headers.cjs --output-dir ../core-c/src/generated"
+  },
+  "files": [
+    "index.js",
+    "math/",
+    "formats/",
+    "constants/",
+    "shaders/",
+    "generate-c-headers.cjs"
+  ],
+  "keywords": [
+    "pixospritz",
+    "game-engine",
+    "specifications"
+  ],
+  "author": "ConflictingTheories",
+  "license": "MIT"
+}

package/shaders/common/lighting.glsl

@@ -0,0 +1,150 @@
+/**
+ * Common Lighting Calculations
+ * Shared GLSL fragment for both JS (WebGL) and C (OpenGL) engines
+ * 
+ * Include this in fragment shaders that need lighting:
+ * #include "lighting.glsl"
+ */
+
+// Maximum number of lights supported
+#define MAX_LIGHTS 8
+
+// Light types
+#define LIGHT_TYPE_POINT 0
+#define LIGHT_TYPE_DIRECTIONAL 1
+#define LIGHT_TYPE_SPOT 2
+
+// Light structure (must match engine uniform layout)
+struct Light {
+    vec3 position;
+    vec3 direction;
+    vec3 color;
+    float intensity;
+    float range;
+    float innerAngle;
+    float outerAngle;
+    int type;
+    bool enabled;
+    bool castShadow;
+};
+
+// Calculate attenuation for point/spot lights
+float calculateAttenuation(float distance, float range) {
+    // Inverse square falloff with range limit
+    float attenuation = 1.0 / (1.0 + distance * distance);
+    
+    // Smooth falloff at range boundary
+    float rangeAttenuation = 1.0 - smoothstep(range * 0.75, range, distance);
+    
+    return attenuation * rangeAttenuation;
+}
+
+// Calculate spot light cone factor
+float calculateSpotFactor(vec3 lightDir, vec3 spotDir, float innerAngle, float outerAngle) {
+    float theta = dot(lightDir, normalize(-spotDir));
+    float epsilon = innerAngle - outerAngle;
+    return clamp((theta - outerAngle) / epsilon, 0.0, 1.0);
+}
+
+// Diffuse lighting (Lambert)
+float calculateDiffuse(vec3 normal, vec3 lightDir) {
+    return max(dot(normal, lightDir), 0.0);
+}
+
+// Specular lighting (Blinn-Phong)
+float calculateSpecular(vec3 normal, vec3 lightDir, vec3 viewDir, float shininess) {
+    vec3 halfDir = normalize(lightDir + viewDir);
+    float specAngle = max(dot(normal, halfDir), 0.0);
+    return pow(specAngle, shininess);
+}
+
+// Calculate contribution from a single light
+vec3 calculateLightContribution(
+    Light light,
+    vec3 fragPos,
+    vec3 normal,
+    vec3 viewDir,
+    vec3 albedo,
+    float shininess
+) {
+    if (!light.enabled) {
+        return vec3(0.0);
+    }
+    
+    vec3 lightDir;
+    float attenuation = 1.0;
+    
+    if (light.type == LIGHT_TYPE_DIRECTIONAL) {
+        // Directional light - no attenuation
+        lightDir = normalize(-light.direction);
+    } else {
+        // Point or spot light
+        vec3 toLight = light.position - fragPos;
+        float distance = length(toLight);
+        lightDir = normalize(toLight);
+        attenuation = calculateAttenuation(distance, light.range);
+        
+        if (light.type == LIGHT_TYPE_SPOT) {
+            // Apply spot cone
+            float spotFactor = calculateSpotFactor(
+                lightDir, 
+                light.direction, 
+                light.innerAngle, 
+                light.outerAngle
+            );
+            attenuation *= spotFactor;
+        }
+    }
+    
+    // Diffuse
+    float diff = calculateDiffuse(normal, lightDir);
+    vec3 diffuse = diff * albedo * light.color;
+    
+    // Specular
+    float spec = calculateSpecular(normal, lightDir, viewDir, shininess);
+    vec3 specular = spec * light.color;
+    
+    return (diffuse + specular) * light.intensity * attenuation;
+}
+
+// Calculate total lighting from all lights
+vec3 calculateTotalLighting(
+    Light lights[MAX_LIGHTS],
+    int numLights,
+    vec3 fragPos,
+    vec3 normal,
+    vec3 viewDir,
+    vec3 albedo,
+    vec3 ambient,
+    float shininess
+) {
+    // Start with ambient
+    vec3 result = ambient * albedo;
+    
+    // Add contribution from each light
+    for (int i = 0; i < MAX_LIGHTS; i++) {
+        if (i >= numLights) break;
+        result += calculateLightContribution(
+            lights[i],
+            fragPos,
+            normal,
+            viewDir,
+            albedo,
+            shininess
+        );
+    }
+    
+    return result;
+}
+
+// Simple ambient occlusion approximation
+float calculateAO(vec3 normal, vec3 up) {
+    float ao = dot(normal, up) * 0.5 + 0.5;
+    return mix(0.5, 1.0, ao);
+}
+
+// Fresnel effect for rim lighting
+float calculateFresnel(vec3 normal, vec3 viewDir, float power) {
+    float fresnel = 1.0 - max(dot(normal, viewDir), 0.0);
+    return pow(fresnel, power);
+}

package/shaders/common/transforms.glsl

@@ -0,0 +1,164 @@
+/**
+ * Common Transform Calculations
+ * Shared GLSL functions for vertex transformations
+ * 
+ * Include this in vertex shaders:
+ * #include "transforms.glsl"
+ */
+
+// Billboard types
+#define BILLBOARD_NONE 0
+#define BILLBOARD_SPHERICAL 1      // Face camera fully
+#define BILLBOARD_CYLINDRICAL 2    // Face camera horizontally only (Y-axis locked)
+#define BILLBOARD_SCREEN 3         // Align to screen plane
+
+/**
+ * Create a billboard rotation matrix that faces the camera
+ * @param viewMatrix The camera's view matrix
+ * @param billboardType Type of billboarding to apply
+ * @return 3x3 rotation matrix for billboard orientation
+ */
+mat3 createBillboardMatrix(mat4 viewMatrix, int billboardType) {
+    if (billboardType == BILLBOARD_NONE) {
+        return mat3(1.0);
+    }
+    
+    // Extract camera right and up vectors from view matrix
+    vec3 right = vec3(viewMatrix[0][0], viewMatrix[1][0], viewMatrix[2][0]);
+    vec3 up = vec3(viewMatrix[0][1], viewMatrix[1][1], viewMatrix[2][1]);
+    vec3 forward = vec3(viewMatrix[0][2], viewMatrix[1][2], viewMatrix[2][2]);
+    
+    if (billboardType == BILLBOARD_CYLINDRICAL) {
+        // Lock Y-axis, only rotate around it
+        up = vec3(0.0, 1.0, 0.0);
+        right = normalize(cross(up, forward));
+        forward = cross(right, up);
+    } else if (billboardType == BILLBOARD_SCREEN) {
+        // Align exactly to screen plane
+        right = vec3(1.0, 0.0, 0.0);
+        up = vec3(0.0, 1.0, 0.0);
+        forward = vec3(0.0, 0.0, 1.0);
+    }
+    
+    return mat3(right, up, forward);
+}
+
+/**
+ * Transform a vertex position for billboard rendering
+ * @param localPos Local vertex position (usually quad corners)
+ * @param worldPos World position of the billboard center
+ * @param scale Scale of the billboard
+ * @param viewMatrix Camera view matrix
+ * @param projMatrix Camera projection matrix
+ * @param billboardType Type of billboarding
+ * @return Clip space position
+ */
+vec4 billboardTransform(
+    vec3 localPos,
+    vec3 worldPos,
+    vec2 scale,
+    mat4 viewMatrix,
+    mat4 projMatrix,
+    int billboardType
+) {
+    mat3 billboardRot = createBillboardMatrix(viewMatrix, billboardType);
+    
+    // Apply scale and rotation to local position
+    vec3 scaledPos = vec3(localPos.x * scale.x, localPos.y * scale.y, localPos.z);
+    vec3 rotatedPos = billboardRot * scaledPos;
+    
+    // Add to world position
+    vec4 worldVertex = vec4(worldPos + rotatedPos, 1.0);
+    
+    // Transform to clip space
+    return projMatrix * viewMatrix * worldVertex;
+}
+
+/**
+ * Apply isometric projection offset
+ * Standard 2:1 isometric ratio
+ */
+vec2 toIsometric(vec3 worldPos) {
+    float isoX = (worldPos.x - worldPos.z) * 0.5;
+    float isoY = (worldPos.x + worldPos.z) * 0.25 - worldPos.y * 0.5;
+    return vec2(isoX, isoY);
+}
+
+/**
+ * Convert screen coordinates to world ray
+ * For picking/raycasting
+ */
+vec3 screenToWorldRay(vec2 screenPos, vec2 screenSize, mat4 invProjMatrix, mat4 invViewMatrix) {
+    // Normalize to [-1, 1]
+    vec2 ndc = (screenPos / screenSize) * 2.0 - 1.0;
+    ndc.y = -ndc.y; // Flip Y
+    
+    // Create clip space position
+    vec4 clipPos = vec4(ndc, -1.0, 1.0);
+    
+    // Transform to view space
+    vec4 viewPos = invProjMatrix * clipPos;
+    viewPos = vec4(viewPos.xy, -1.0, 0.0);
+    
+    // Transform to world space
+    vec3 worldDir = (invViewMatrix * viewPos).xyz;
+    
+    return normalize(worldDir);
+}
+
+/**
+ * Calculate sprite depth for proper sorting
+ * Considers Y position for top-down games
+ */
+float calculateSpriteDepth(vec3 worldPos, float yBias) {
+    // Base depth from Z
+    float depth = worldPos.z;
+    
+    // Add Y bias for proper sprite stacking
+    depth += worldPos.y * yBias;
+    
+    return depth;
+}
+
+/**
+ * UV coordinate transformations for sprite sheets
+ */
+vec2 transformUV(vec2 uv, vec2 frameOffset, vec2 frameSize, vec2 sheetSize) {
+    vec2 normalizedOffset = frameOffset / sheetSize;
+    vec2 normalizedSize = frameSize / sheetSize;
+    return normalizedOffset + uv * normalizedSize;
+}
+
+/**
+ * Flip UV coordinates
+ */
+vec2 flipUV(vec2 uv, bool flipX, bool flipY) {
+    if (flipX) uv.x = 1.0 - uv.x;
+    if (flipY) uv.y = 1.0 - uv.y;
+    return uv;
+}
+
+/**
+ * Rotate UV coordinates
+ * @param uv UV coordinates
+ * @param angle Rotation in radians
+ * @param center Rotation center (usually 0.5, 0.5)
+ */
+vec2 rotateUV(vec2 uv, float angle, vec2 center) {
+    float s = sin(angle);
+    float c = cos(angle);
+    vec2 offset = uv - center;
+    return vec2(
+        offset.x * c - offset.y * s,
+        offset.x * s + offset.y * c
+    ) + center;
+}
+
+/**
+ * Calculate parallax offset for depth effects
+ */
+vec2 parallaxOffset(vec2 uv, vec3 viewDir, float height, float scale) {
+    float h = height * scale;
+    vec2 offset = viewDir.xy / viewDir.z * h;
+    return uv - offset;
+}