cubeforge 0.8.1 → 0.8.3

package/dist/index.d.ts

@@ -146,6 +146,12 @@ interface SpriteProps {
     height: number;
     color?: string;
     src?: string;
+    /**
+     * ID returned by `useDynamicCanvas()`. When set the sprite samples from
+     * the registered canvas texture and re-uploads it whenever `markDirty()`
+     * is called on that handle.
+     */
+    dynamicSrc?: string;
     offsetX?: number;
     offsetY?: number;
     zIndex?: number;
@@ -191,7 +197,7 @@ interface SpriteProps {
     /** Inner radius ratio for 'star' shape (0-1, default 0.4) */
     starInnerRadius?: number;
 }
-declare function Sprite({ width, height, color, src, offsetX, offsetY, zIndex, visible, flipX, flipY, anchorX, anchorY, frameIndex, frameWidth, frameHeight, frameColumns, atlas, frame, tileX, tileY, tileSizeX, tileSizeY, sampling, blendMode, layer, tint, tintOpacity, opacity, shape, borderRadius, strokeColor, strokeWidth, customDraw, starPoints, starInnerRadius, }: SpriteProps): null;
+declare function Sprite({ width, height, color, src, dynamicSrc, offsetX, offsetY, zIndex, visible, flipX, flipY, anchorX, anchorY, frameIndex, frameWidth, frameHeight, frameColumns, atlas, frame, tileX, tileY, tileSizeX, tileSizeY, sampling, blendMode, layer, tint, tintOpacity, opacity, shape, borderRadius, strokeColor, strokeWidth, customDraw, starPoints, starInnerRadius, }: SpriteProps): null;
 
 interface TextProps {
     text: string;
@@ -1900,6 +1906,84 @@ declare function usePostProcess(effect: PostProcessEffect): void;
  */
 declare function useWebGLPostProcess(opts: PostProcessOptions): void;
 
+interface DynamicCanvasHandle {
+    /** Unique ID — pass to `<Sprite dynamicSrc={...}>` to display this canvas. */
+    readonly id: string;
+    /** The offscreen canvas you draw onto. */
+    readonly canvas: HTMLCanvasElement;
+    /** 2D drawing context for the canvas. */
+    readonly ctx: CanvasRenderingContext2D;
+    /**
+     * Call after drawing to schedule a GPU upload before the next frame.
+     * The renderer uses `texSubImage2D` to re-upload only when dirty,
+     * so skipping this call when the canvas hasn't changed avoids unnecessary
+     * CPU→GPU transfers.
+     */
+    markDirty(): void;
+}
+/**
+ * Creates a CPU-side canvas that is uploaded to the GPU as a sprite texture.
+ * Only re-uploads when you call `markDirty()` — skipping frames where the
+ * canvas content hasn't changed avoids redundant `texSubImage2D` calls.
+ *
+ * Useful for minimaps, procedural textures, dynamic UI painted with Canvas2D,
+ * or any per-frame canvas drawing that shouldn't upload every RAF tick.
+ *
+ * @param width  - Canvas width in pixels.
+ * @param height - Canvas height in pixels.
+ *
+ * @example
+ * ```tsx
+ * function Minimap() {
+ *   const { id, ctx, canvas, markDirty } = useDynamicCanvas(128, 128)
+ *
+ *   useFrame(() => {
+ *     ctx.clearRect(0, 0, canvas.width, canvas.height)
+ *     // ...draw minimap content...
+ *     markDirty()
+ *   })
+ *
+ *   return (
+ *     <Entity>
+ *       <Transform x={-200} y={-150} />
+ *       <Sprite width={128} height={128} dynamicSrc={id} />
+ *     </Entity>
+ *   )
+ * }
+ * ```
+ */
+declare function useDynamicCanvas(width: number, height: number): DynamicCanvasHandle;
+
+/**
+ * Enables the WebGL renderer's idle frame skip optimisation.
+ *
+ * When enabled the renderer hashes visible entity positions, animation frame
+ * indices, and camera state every tick. If the hash matches the previous frame
+ * the GPU draw calls are skipped entirely and the cached scene is blitted to
+ * screen instead — saving significant CPU/GPU work in static or low-motion
+ * scenes (pause screens, dialogue boxes, turn-based games).
+ *
+ * Active particle systems and playing animations automatically force a redraw
+ * even when the rest of the scene is unchanged.
+ *
+ * Call this once at the game or scene root level:
+ *
+ * @example
+ * ```tsx
+ * function GameScene() {
+ *   useIdleFrameSkip()
+ *   return <>{children}</>
+ * }
+ * ```
+ *
+ * Pass `false` to disable it (e.g. in a child component that needs full
+ * redraws while a cutscene plays):
+ * ```tsx
+ * useIdleFrameSkip(false)
+ * ```
+ */
+declare function useIdleFrameSkip(enabled?: boolean): void;
+
 /**
  * Automatically syncs the Web Audio API listener position to the Camera2D
  * entity each frame, enabling accurate positional audio for spatial sounds.
@@ -3627,4 +3711,4 @@ declare function useRemotePlayer(config: {
     opts?: RemotePlayerOptions;
 }): RemotePlayerControls;
 
-export { A11yNode, type A11yNodeProps, type AccessibilityControls, AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, Animator, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraBlendControls, type CameraControls, type CameraLookaheadOptions, CameraZone, CapsuleCollider, Checkpoint, type CinematicSequenceControls, type CinematicStep, Circle, CircleCollider, type ComboDetectorResult, CompoundCollider, ConvexCollider, type CoordinateHelpers, type CoroutineControls, type CoroutineFactory, type CoroutineYield, type DraggableControls, type DraggableOptions, type DroppableControls, type DroppableOptions, EditableText, type EditableTextProps, Entity, type ExportOptions, FocusRing, type FocusRingProps, type FocusableOptions, Game, type GameControls, type GamepadState, type GestureHandlers, type GestureOptions, Gradient, type GridCell, type GridControls, type GridOptions, type HMRControls, HUD, HUDBar, type HUDBarProps, HUDCounter, type HUDCounterProps, type HUDPosition, type HUDProps, HUDZone, type HUDZoneProps, HalfSpaceCollider, HeightFieldCollider, type HistoryControls, type HistoryOptions, type HoverableControls, type HoverableOptions, type InputContextControls, Joint, type KeyboardFocusControls, Line, Mask, MovingPlatform, type NetworkSyncOptions, NineSlice, PARTICLE_PRESETS, ParallaxLayer, ParticleEmitter, type ParticleEmitterConfig, type ParticlePreset, type PauseControls, type PinchEvent, Polygon, type PreloadState, type ProfilerData, type RemotePlayerControls, type RemotePlayerOptions, RigidBody, type SceneManagerControls, type SceneSaveOptions, type SceneTransitionControls, SceneTransitionOverlay, ScreenFlash, type ScreenFlashHandle, Script, SegmentCollider, type SelectOptions, Selection, type SelectionControls, type SelectionProps, type SnapControls, type SnapOptions, type SnapResult, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, type SquashStretchControls, Stage, type SwipeEvent, Text, type TiledLayer, type TiledObject, Tilemap, type TimerControls, type TouchControls, type TouchHapticsControls, Trail, Transform, TransformHandles, type TransformHandlesProps, type TransitionEffect, TriMeshCollider, TriangleCollider, type TurnSystemControls, type TurnSystemOptions, VectorPath, type VectorPathProps, VirtualCamera, type VirtualCameraConfig, type VirtualCameraProps, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, type Waypoint, World, createAtlas, defineAnimations, definePrefab, deleteSavedScene, downloadCanvas, exportToBlob, exportToDataURL, listSavedScenes, loadScene, loadSceneFromLocalStorage, playClip, saveScene, saveSceneToLocalStorage, setAnimationState, setAnimatorParam, useAccessibility, useAudioListener, useCamera, useCameraBlend, useCameraLookahead, useCinematicSequence, useComboDetector, useCoordinates, useCoroutine, useDestroyEntity, useDraggable, useDroppable, useEntity, useEvent, useEvents, useFocusable, useGame, useGamepad, useGamepadHaptics, useGestures, useGrid, useHMR, useHistory, useHitstop, useHoverable, useInput, useInputBuffer, useInputContext, useInputMap, useInputRecorder, useKeyboardFocus, useLocalMultiplayer, useNetworkSync, useParent, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useRemotePlayer, useSceneManager, useSceneTransition, useSelection, useSnap, useSnapshot, useSquashStretch, useTimer, useTouch, useTouchHaptics, useTurnSystem, useVirtualInput, useWebGLPostProcess, useWorldQuery, wait, waitFrames, waitUntil };
+export { A11yNode, type A11yNodeProps, type AccessibilityControls, AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, Animator, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraBlendControls, type CameraControls, type CameraLookaheadOptions, CameraZone, CapsuleCollider, Checkpoint, type CinematicSequenceControls, type CinematicStep, Circle, CircleCollider, type ComboDetectorResult, CompoundCollider, ConvexCollider, type CoordinateHelpers, type CoroutineControls, type CoroutineFactory, type CoroutineYield, type DraggableControls, type DraggableOptions, type DroppableControls, type DroppableOptions, type DynamicCanvasHandle, EditableText, type EditableTextProps, Entity, type ExportOptions, FocusRing, type FocusRingProps, type FocusableOptions, Game, type GameControls, type GamepadState, type GestureHandlers, type GestureOptions, Gradient, type GridCell, type GridControls, type GridOptions, type HMRControls, HUD, HUDBar, type HUDBarProps, HUDCounter, type HUDCounterProps, type HUDPosition, type HUDProps, HUDZone, type HUDZoneProps, HalfSpaceCollider, HeightFieldCollider, type HistoryControls, type HistoryOptions, type HoverableControls, type HoverableOptions, type InputContextControls, Joint, type KeyboardFocusControls, Line, Mask, MovingPlatform, type NetworkSyncOptions, NineSlice, PARTICLE_PRESETS, ParallaxLayer, ParticleEmitter, type ParticleEmitterConfig, type ParticlePreset, type PauseControls, type PinchEvent, Polygon, type PreloadState, type ProfilerData, type RemotePlayerControls, type RemotePlayerOptions, RigidBody, type SceneManagerControls, type SceneSaveOptions, type SceneTransitionControls, SceneTransitionOverlay, ScreenFlash, type ScreenFlashHandle, Script, SegmentCollider, type SelectOptions, Selection, type SelectionControls, type SelectionProps, type SnapControls, type SnapOptions, type SnapResult, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, type SquashStretchControls, Stage, type SwipeEvent, Text, type TiledLayer, type TiledObject, Tilemap, type TimerControls, type TouchControls, type TouchHapticsControls, Trail, Transform, TransformHandles, type TransformHandlesProps, type TransitionEffect, TriMeshCollider, TriangleCollider, type TurnSystemControls, type TurnSystemOptions, VectorPath, type VectorPathProps, VirtualCamera, type VirtualCameraConfig, type VirtualCameraProps, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, type Waypoint, World, createAtlas, defineAnimations, definePrefab, deleteSavedScene, downloadCanvas, exportToBlob, exportToDataURL, listSavedScenes, loadScene, loadSceneFromLocalStorage, playClip, saveScene, saveSceneToLocalStorage, setAnimationState, setAnimatorParam, useAccessibility, useAudioListener, useCamera, useCameraBlend, useCameraLookahead, useCinematicSequence, useComboDetector, useCoordinates, useCoroutine, useDestroyEntity, useDraggable, useDroppable, useDynamicCanvas, useEntity, useEvent, useEvents, useFocusable, useGame, useGamepad, useGamepadHaptics, useGestures, useGrid, useHMR, useHistory, useHitstop, useHoverable, useIdleFrameSkip, useInput, useInputBuffer, useInputContext, useInputMap, useInputRecorder, useKeyboardFocus, useLocalMultiplayer, useNetworkSync, useParent, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useRemotePlayer, useSceneManager, useSceneTransition, useSelection, useSnap, useSnapshot, useSquashStretch, useTimer, useTouch, useTouchHaptics, useTurnSystem, useVirtualInput, useWebGLPostProcess, useWorldQuery, wait, waitFrames, waitUntil };