cubeforge 0.3.10 → 0.3.11

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import * as React from 'react';
 import React__default, { CSSProperties, ReactNode } from 'react';
 import { Plugin, EntityId, ECSWorld, ScriptUpdateFn, NavGrid, WorldSnapshot, EventBus } from '@cubeforge/core';
 export { AssetProgress, Component, ECSWorld, Ease, EntityId, GameTimer, HotReloadablePlugin, NavGrid, Plugin, PreloadManifest, ScriptUpdateFn, TransformComponent, TweenHandle, Vec2Like, WorldSnapshot, arrive, createTag, createTimer, createTransform, definePlugin, findByTag, flee, hotReloadPlugin, patrol, preloadManifest, seek, tween, wander } from '@cubeforge/core';
+import { Sampling } from '@cubeforge/renderer';
+export { AnimationStateComponent, MagFilterValue, NineSliceComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, RenderSystem, Sampling, SpriteComponent, SquashStretchComponent, TextComponent, TextureFilter, TextureFilterValue, TrailComponent, createNineSlice, createSprite } from '@cubeforge/renderer';
 import { ColliderShape } from '@cubeforge/physics';
 export { BoxColliderComponent, CapsuleColliderComponent, CircleColliderComponent, ColliderShape, CompoundColliderComponent, RaycastHit, RigidBodyComponent, createCompoundCollider, overlapBox, overlapCircle, raycast, raycastAll, sweepBox } from '@cubeforge/physics';
 import { InputManager, ActionBindings, InputContextName, PlayerInput, InputRecorderControls } from '@cubeforge/input';
@@ -12,7 +14,6 @@ export { EngineState, useCircleEnter, useCircleExit, useCircleStay, useCollision
 export { AISteering, AnimationClip, AnimationControllerResult, BindingControls, CutsceneControls, CutsceneStep, DialogueControls, DialogueLine, DialogueScript, GameState as GameStateDefinition, GameStateMachineResult, HealthControls, HealthOptions, KinematicBodyControls, LevelTransitionControls, PathfindingControls, PlatformerControllerOptions, RestartControls, SaveControls, SaveOptions, TopDownMovementOptions, TransitionOptions, TransitionType, useAISteering, useAnimationController, useCutscene, useDamageZone, useDialogue, useDropThrough, useGameStateMachine, useGameStore, useHealth, useKinematicBody, useLevelTransition, usePathfinding, usePersistedBindings, usePlatformerController, useRestart, useSave, useTopDownMovement } from '@cubeforge/gameplay';
 export { AudioGroup, SoundControls, duck, getGroupVolume, setGroupMute, setGroupVolume, setMasterVolume, stopGroup, useSound } from '@cubeforge/audio';
 export { DevToolsHandle } from '@cubeforge/devtools';
-export { AnimationStateComponent, NineSliceComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, RenderSystem, SpriteComponent, SquashStretchComponent, TextComponent, TrailComponent, createNineSlice, createSprite } from '@cubeforge/renderer';
 
 interface GameControls {
     pause(): void;
@@ -48,13 +49,19 @@ interface GameProps {
      * shown is fully rendered with real assets.
      */
     asyncAssets?: boolean;
+    /**
+     * Default texture sampling for all sprites (default 'nearest').
+     * Individual sprites can override via their own `sampling` prop.
+     * Use `TextureFilter.NEAREST` for pixel art or `TextureFilter.LINEAR` for smooth scaling.
+     */
+    sampling?: Sampling;
     /** Custom plugins to register after core systems. Each plugin's systems run after Render. */
     plugins?: Plugin[];
     style?: CSSProperties;
     className?: string;
     children?: React__default.ReactNode;
 }
-declare function Game({ width, height, gravity, debug, devtools, scale, deterministic, seed, asyncAssets, onReady, plugins, style, className, children, }: GameProps): react_jsx_runtime.JSX.Element;
+declare function Game({ width, height, gravity, debug, devtools, scale, deterministic, seed, asyncAssets, sampling, onReady, plugins, style, className, children, }: GameProps): react_jsx_runtime.JSX.Element;
 
 interface WorldProps {
     /** Gravitational acceleration in pixels/s² (default inherited from Game) */
@@ -114,8 +121,10 @@ interface SpriteProps {
     tileY?: boolean;
     tileSizeX?: number;
     tileSizeY?: number;
+    /** Texture sampling mode — controls filtering when the sprite is scaled */
+    sampling?: Sampling;
 }
-declare function Sprite({ width, height, color, src, offsetX, offsetY, zIndex, visible, flipX, anchorX, anchorY, frameIndex, frameWidth, frameHeight, frameColumns, atlas, frame, tileX, tileY, tileSizeX, tileSizeY, }: SpriteProps): null;
+declare function Sprite({ width, height, color, src, offsetX, offsetY, zIndex, visible, flipX, anchorX, anchorY, frameIndex, frameWidth, frameHeight, frameColumns, atlas, frame, tileX, tileY, tileSizeX, tileSizeY, sampling, }: SpriteProps): null;
 
 interface TextProps {
     text: string;

package/dist/index.js

@@ -1146,6 +1146,55 @@ function createSprite(opts) {
   };
 }
 
+// ../../packages/renderer/src/textureFilter.ts
+var TextureFilter = {
+  /** Nearest-neighbor — sharp pixels, ideal for pixel art */
+  NEAREST: "nearest",
+  /** Bilinear — smooth interpolation */
+  LINEAR: "linear",
+  /** Nearest on nearest mipmap level */
+  NEAREST_MIPMAP_NEAREST: "nearest-mipmap-nearest",
+  /** Bilinear on nearest mipmap level */
+  LINEAR_MIPMAP_NEAREST: "linear-mipmap-nearest",
+  /** Nearest, blending between two mipmap levels */
+  NEAREST_MIPMAP_LINEAR: "nearest-mipmap-linear",
+  /** Trilinear — bilinear + mipmap blending, smoothest downscaling */
+  LINEAR_MIPMAP_LINEAR: "linear-mipmap-linear"
+};
+var DEFAULT_SAMPLING = TextureFilter.NEAREST;
+function resolveSampling(sampling, fallback = DEFAULT_SAMPLING) {
+  const s2 = sampling ?? fallback;
+  if (typeof s2 === "string") {
+    const mag = s2.startsWith("linear") ? "linear" : "nearest";
+    return { min: s2, mag };
+  }
+  return { min: s2.min, mag: s2.mag };
+}
+function toGLMinFilter(gl, filter) {
+  switch (filter) {
+    case "nearest":
+      return gl.NEAREST;
+    case "linear":
+      return gl.LINEAR;
+    case "nearest-mipmap-nearest":
+      return gl.NEAREST_MIPMAP_NEAREST;
+    case "linear-mipmap-nearest":
+      return gl.LINEAR_MIPMAP_NEAREST;
+    case "nearest-mipmap-linear":
+      return gl.NEAREST_MIPMAP_LINEAR;
+    case "linear-mipmap-linear":
+      return gl.LINEAR_MIPMAP_LINEAR;
+    default:
+      return gl.NEAREST;
+  }
+}
+function toGLMagFilter(gl, filter) {
+  return filter === "linear" ? gl.LINEAR : gl.NEAREST;
+}
+function needsMipmap(filter) {
+  return filter !== "nearest" && filter !== "linear";
+}
+
 // ../../packages/renderer/src/components/camera2d.ts
 function createCamera2D(opts) {
   return {
@@ -1367,10 +1416,17 @@ function createWhiteTexture(gl) {
   gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
   return tex;
 }
+function getSamplingKey(sampling) {
+  if (!sampling) return "";
+  if (typeof sampling === "string") return sampling;
+  return `${sampling.min}|${sampling.mag}`;
+}
 function getTextureKey(sprite) {
   const src = sprite.image?.src || sprite.src;
-  if (src) return sprite.tileX || sprite.tileY ? `${src}:repeat` : src;
-  return `__color__:${sprite.color}`;
+  const samplingKey = getSamplingKey(sprite.sampling);
+  const suffix = samplingKey ? `:s=${samplingKey}` : "";
+  if (src) return sprite.tileX || sprite.tileY ? `${src}:repeat${suffix}` : `${src}${suffix}`;
+  return `__color__:${sprite.color}${suffix}`;
 }
 function getUVRect(sprite) {
   if (!sprite.image || sprite.image.naturalWidth === 0) return [0, 0, 1, 1];
@@ -1528,6 +1584,16 @@ var RenderSystem = class {
   textureCache = /* @__PURE__ */ new Map();
   /** Insertion-order key list for LRU-style eviction. */
   textureCacheKeys = [];
+  // ── Texture sampling ────────────────────────────────────────────────────
+  _defaultSampling = DEFAULT_SAMPLING;
+  /** Set the global default texture sampling mode for all sprites that don't specify their own. */
+  setDefaultSampling(sampling) {
+    this._defaultSampling = sampling;
+  }
+  /** Get the current global default texture sampling mode. */
+  getDefaultSampling() {
+    return this._defaultSampling;
+  }
   // ── Debug overlays ──────────────────────────────────────────────────────
   debugNavGrid = null;
   contactFlashPoints = [];
@@ -1546,16 +1612,18 @@ var RenderSystem = class {
   loadTexture(src) {
     const cached = this.textures.get(src);
     if (cached) return cached;
-    const imgSrc = src.endsWith(":repeat") ? src.slice(0, -7) : src;
+    let imgSrc = src;
+    const sampIdx = imgSrc.indexOf(":s=");
+    if (sampIdx !== -1) imgSrc = imgSrc.slice(0, sampIdx);
+    if (imgSrc.endsWith(":repeat")) imgSrc = imgSrc.slice(0, -7);
     const existing = this.imageCache.get(imgSrc);
     if (existing && existing.complete && existing.naturalWidth > 0) {
       const gl = this.gl;
       const tex = gl.createTexture();
       gl.bindTexture(gl.TEXTURE_2D, tex);
       gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, existing);
-      gl.generateMipmap(gl.TEXTURE_2D);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
       gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
       gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
       this.textures.set(src, tex);
@@ -1564,15 +1632,14 @@ var RenderSystem = class {
     if (!existing) {
       const img = new Image();
       img.src = imgSrc;
-      const tiled = src.endsWith(":repeat");
+      const tiled = src.includes(":repeat");
       img.onload = () => {
         const gl = this.gl;
         const tex = gl.createTexture();
         gl.bindTexture(gl.TEXTURE_2D, tex);
         gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
-        gl.generateMipmap(gl.TEXTURE_2D);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
         const wrap = tiled ? gl.REPEAT : gl.CLAMP_TO_EDGE;
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, wrap);
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, wrap);
@@ -1595,9 +1662,8 @@ var RenderSystem = class {
         const tex = gl.createTexture();
         gl.bindTexture(gl.TEXTURE_2D, tex);
         gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
-        gl.generateMipmap(gl.TEXTURE_2D);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.REPEAT);
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.REPEAT);
         this.parallaxTextures.set(src, tex);
@@ -1640,9 +1706,8 @@ var RenderSystem = class {
     const tex = gl.createTexture();
     gl.bindTexture(gl.TEXTURE_2D, tex);
     gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, offscreen);
-    gl.generateMipmap(gl.TEXTURE_2D);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
     const entry = { tex, w: textW, h: textH };
@@ -1650,13 +1715,23 @@ var RenderSystem = class {
     this.textureCacheKeys.push(key);
     return entry;
   }
+  // ── Texture sampling helper ────────────────────────────────────────────────
+  /** Apply min/mag filter params to the currently bound texture. */
+  applySampling(spriteSampling) {
+    const { gl } = this;
+    const { min, mag } = resolveSampling(spriteSampling, this._defaultSampling);
+    if (needsMipmap(min)) gl.generateMipmap(gl.TEXTURE_2D);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, toGLMinFilter(gl, min));
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, toGLMagFilter(gl, mag));
+  }
   // ── Instanced draw call ────────────────────────────────────────────────────
-  flush(count, textureKey) {
+  flush(count, textureKey, sampling) {
     if (count === 0) return;
     const { gl } = this;
     const isColor = textureKey.startsWith("__color__");
     const tex = isColor ? this.whiteTexture : this.loadTexture(textureKey);
     gl.bindTexture(gl.TEXTURE_2D, tex);
+    this.applySampling(sampling);
     gl.uniform1i(this.uUseTexture, isColor ? 0 : 1);
     gl.bindVertexArray(this.quadVAO);
     gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceBuffer);
@@ -1835,9 +1910,10 @@ var RenderSystem = class {
     });
     let batchCount = 0;
     let batchKey = "";
+    let batchSampling;
     for (let i = 0; i <= renderables.length; i++) {
       if (i === renderables.length) {
-        this.flush(batchCount, batchKey);
+        this.flush(batchCount, batchKey, batchSampling);
         break;
       }
       const id = renderables[i];
@@ -1852,9 +1928,8 @@ var RenderSystem = class {
           const tex = gl2.createTexture();
           gl2.bindTexture(gl2.TEXTURE_2D, tex);
           gl2.texImage2D(gl2.TEXTURE_2D, 0, gl2.RGBA, gl2.RGBA, gl2.UNSIGNED_BYTE, sprite.image);
-          gl2.generateMipmap(gl2.TEXTURE_2D);
-          gl2.texParameteri(gl2.TEXTURE_2D, gl2.TEXTURE_MIN_FILTER, gl2.LINEAR_MIPMAP_LINEAR);
-          gl2.texParameteri(gl2.TEXTURE_2D, gl2.TEXTURE_MAG_FILTER, gl2.LINEAR);
+          gl2.texParameteri(gl2.TEXTURE_2D, gl2.TEXTURE_MIN_FILTER, gl2.NEAREST);
+          gl2.texParameteri(gl2.TEXTURE_2D, gl2.TEXTURE_MAG_FILTER, gl2.NEAREST);
           const wrap = tiled ? gl2.REPEAT : gl2.CLAMP_TO_EDGE;
           gl2.texParameteri(gl2.TEXTURE_2D, gl2.TEXTURE_WRAP_S, wrap);
           gl2.texParameteri(gl2.TEXTURE_2D, gl2.TEXTURE_WRAP_T, wrap);
@@ -1871,9 +1946,8 @@ var RenderSystem = class {
             const tex = gl2.createTexture();
             gl2.bindTexture(gl2.TEXTURE_2D, tex);
             gl2.texImage2D(gl2.TEXTURE_2D, 0, gl2.RGBA, gl2.RGBA, gl2.UNSIGNED_BYTE, img);
-            gl2.generateMipmap(gl2.TEXTURE_2D);
-            gl2.texParameteri(gl2.TEXTURE_2D, gl2.TEXTURE_MIN_FILTER, gl2.LINEAR_MIPMAP_LINEAR);
-            gl2.texParameteri(gl2.TEXTURE_2D, gl2.TEXTURE_MAG_FILTER, gl2.LINEAR);
+            gl2.texParameteri(gl2.TEXTURE_2D, gl2.TEXTURE_MIN_FILTER, gl2.NEAREST);
+            gl2.texParameteri(gl2.TEXTURE_2D, gl2.TEXTURE_MAG_FILTER, gl2.NEAREST);
             this.textures.set(img.src, tex);
           };
         }
@@ -1881,10 +1955,11 @@ var RenderSystem = class {
       }
       const key = getTextureKey(sprite);
       if (key !== batchKey && batchCount > 0 || batchCount >= MAX_INSTANCES) {
-        this.flush(batchCount, batchKey);
+        this.flush(batchCount, batchKey, batchSampling);
         batchCount = 0;
       }
       batchKey = key;
+      batchSampling = sprite.sampling;
       const ss = world.getComponent(id, "SquashStretch");
       const scaleXMod = ss ? ss.currentScaleX : 1;
       const scaleYMod = ss ? ss.currentScaleY : 1;
@@ -1926,9 +2001,10 @@ var RenderSystem = class {
       if (!text.visible) continue;
       const entry = this.getOrCreateTextTexture(text);
       if (!entry) continue;
-      this.flush(batchCount, batchKey);
+      this.flush(batchCount, batchKey, batchSampling);
       batchCount = 0;
       batchKey = "";
+      batchSampling = void 0;
       this.writeInstance(
         0,
         transform.x + text.offsetX,
@@ -3788,6 +3864,7 @@ function Game({
   deterministic = false,
   seed = 0,
   asyncAssets = false,
+  sampling,
   onReady,
   plugins,
   style,
@@ -3810,6 +3887,7 @@ function Game({
     const physics = new PhysicsSystem(gravity, events);
     const entityIds = /* @__PURE__ */ new Map();
     const renderSystem = new RenderSystem(canvas, entityIds);
+    if (sampling) renderSystem.setDefaultSampling(sampling);
     const activeRenderSystem = renderSystem;
     let debugSystem = null;
     if (debug) {
@@ -4101,7 +4179,8 @@ function Sprite({
   tileX,
   tileY,
   tileSizeX,
-  tileSizeY
+  tileSizeY,
+  sampling
 }) {
   const resolvedFrameIndex = atlas && frame != null ? atlas[frame] ?? 0 : frameIndex;
   const engine = useContext5(EngineContext);
@@ -4126,7 +4205,8 @@ function Sprite({
       tileX,
       tileY,
       tileSizeX,
-      tileSizeY
+      tileSizeY,
+      sampling
     });
     engine.ecs.addComponent(entityId, comp);
     if (src) {
@@ -6394,6 +6474,7 @@ export {
   Sprite,
   SquashStretch,
   Text,
+  TextureFilter,
   Tilemap,
   Trail,
   Transform,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cubeforge",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "React-first 2D browser game engine",
   "type": "module",
   "main": "./dist/index.js",