@thewhateverapp/tile-sdk 0.17.6 → 0.17.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -4,6 +4,10 @@
|
|
|
4
4
|
* This component creates an Excalibur Engine imperatively and provides
|
|
5
5
|
* it via React context for game development.
|
|
6
6
|
*
|
|
7
|
+
* IMPORTANT: This component is NOT SSR-safe. Excalibur.js requires browser APIs.
|
|
8
|
+
* The component automatically handles SSR by rendering a loading placeholder
|
|
9
|
+
* until the client-side code is ready.
|
|
10
|
+
*
|
|
7
11
|
* @example
|
|
8
12
|
* ```tsx
|
|
9
13
|
* import { ExcaliburGame, useEngine, useGameLoop } from '@thewhateverapp/tile-sdk/excalibur';
|
|
@@ -43,7 +47,6 @@
|
|
|
43
47
|
* ```
|
|
44
48
|
*/
|
|
45
49
|
import React, { type ReactNode } from 'react';
|
|
46
|
-
import { Engine, DisplayMode, type Scene } from 'excalibur';
|
|
47
50
|
export { Actor, Vector, Color, Engine, Scene, Timer, Trigger, Label } from 'excalibur';
|
|
48
51
|
export { Sprite, SpriteSheet, Animation, AnimationStrategy, AnimationDirection, Graphic, GraphicsGroup, Rectangle, Circle, Polygon, Line, Text, Font, Canvas, ImageFiltering, ImageWrapping, } from 'excalibur';
|
|
49
52
|
export { ImageSource, Sound, Loader, DefaultLoader, Resource, Gif, } from 'excalibur';
|
|
@@ -60,18 +63,23 @@ export { PreUpdateEvent, PostUpdateEvent, PreDrawEvent, PostDrawEvent, Collision
|
|
|
60
63
|
export { coroutine } from 'excalibur';
|
|
61
64
|
export { Logger, LogLevel, EasingFunction } from 'excalibur';
|
|
62
65
|
/**
|
|
63
|
-
* Game dimensions -
|
|
66
|
+
* Game dimensions - optimized for mobile performance (9:16 aspect ratio)
|
|
67
|
+
* Full page view: 540x960 (half of Full HD)
|
|
68
|
+
* Tile view: 360x640 (optimized for 256x554 tile container)
|
|
64
69
|
*/
|
|
65
|
-
export declare const GAME_WIDTH =
|
|
66
|
-
export declare const GAME_HEIGHT =
|
|
70
|
+
export declare const GAME_WIDTH = 540;
|
|
71
|
+
export declare const GAME_HEIGHT = 960;
|
|
72
|
+
/** Tile view dimensions - use these when rendering in tile (256x554) container */
|
|
73
|
+
export declare const TILE_GAME_WIDTH = 360;
|
|
74
|
+
export declare const TILE_GAME_HEIGHT = 640;
|
|
67
75
|
/**
|
|
68
76
|
* Hook to get the Excalibur Engine
|
|
69
77
|
*/
|
|
70
|
-
export declare function useEngine(): Engine | null;
|
|
78
|
+
export declare function useEngine(): import('excalibur').Engine | null;
|
|
71
79
|
/**
|
|
72
80
|
* Hook to get the current scene
|
|
73
81
|
*/
|
|
74
|
-
export declare function useScene(): Scene | null;
|
|
82
|
+
export declare function useScene(): import('excalibur').Scene | null;
|
|
75
83
|
/**
|
|
76
84
|
* useGameLoop - Run a callback every frame
|
|
77
85
|
*
|
|
@@ -81,14 +89,14 @@ export declare function useScene(): Scene | null;
|
|
|
81
89
|
export declare function useGameLoop(callback: (delta: number) => void, enabled?: boolean): void;
|
|
82
90
|
export interface ExcaliburGameProps {
|
|
83
91
|
children: ReactNode;
|
|
84
|
-
/** Width in pixels (default:
|
|
92
|
+
/** Width in pixels (default: 540 for page view, use TILE_GAME_WIDTH=360 for tile view) */
|
|
85
93
|
width?: number;
|
|
86
|
-
/** Height in pixels (default:
|
|
94
|
+
/** Height in pixels (default: 960 for page view, use TILE_GAME_HEIGHT=640 for tile view) */
|
|
87
95
|
height?: number;
|
|
88
96
|
/** Background color (CSS color string, default: black) */
|
|
89
97
|
backgroundColor?: string;
|
|
90
98
|
/** Display mode (default: FitContainerAndFill - scales to fill container) */
|
|
91
|
-
displayMode?: DisplayMode;
|
|
99
|
+
displayMode?: import('excalibur').DisplayMode;
|
|
92
100
|
/** Game options */
|
|
93
101
|
options?: {
|
|
94
102
|
antialiasing?: boolean;
|
|
@@ -98,13 +106,16 @@ export interface ExcaliburGameProps {
|
|
|
98
106
|
/** Whether game is paused */
|
|
99
107
|
paused?: boolean;
|
|
100
108
|
/** Callback when Engine is ready */
|
|
101
|
-
onMount?: (engine: Engine) => void;
|
|
109
|
+
onMount?: (engine: import('excalibur').Engine) => void;
|
|
102
110
|
}
|
|
103
111
|
/**
|
|
104
112
|
* ExcaliburGame - Main wrapper component for Excalibur.js games
|
|
105
113
|
*
|
|
106
114
|
* Creates an Excalibur Engine and provides it via context.
|
|
107
115
|
* Children can use useEngine() to access the engine and add actors/entities.
|
|
116
|
+
*
|
|
117
|
+
* This component handles SSR gracefully by rendering a loading placeholder
|
|
118
|
+
* until the client-side Excalibur engine is ready.
|
|
108
119
|
*/
|
|
109
120
|
export declare function ExcaliburGame({ children, width, height, backgroundColor, displayMode, options, paused, onMount, }: ExcaliburGameProps): React.JSX.Element;
|
|
110
121
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ExcaliburGame.d.ts","sourceRoot":"","sources":["../../src/react/ExcaliburGame.tsx"],"names":[],"mappings":"AAEA
|
|
1
|
+
{"version":3,"file":"ExcaliburGame.d.ts","sourceRoot":"","sources":["../../src/react/ExcaliburGame.tsx"],"names":[],"mappings":"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"}
|
|
@@ -5,6 +5,10 @@
|
|
|
5
5
|
* This component creates an Excalibur Engine imperatively and provides
|
|
6
6
|
* it via React context for game development.
|
|
7
7
|
*
|
|
8
|
+
* IMPORTANT: This component is NOT SSR-safe. Excalibur.js requires browser APIs.
|
|
9
|
+
* The component automatically handles SSR by rendering a loading placeholder
|
|
10
|
+
* until the client-side code is ready.
|
|
11
|
+
*
|
|
8
12
|
* @example
|
|
9
13
|
* ```tsx
|
|
10
14
|
* import { ExcaliburGame, useEngine, useGameLoop } from '@thewhateverapp/tile-sdk/excalibur';
|
|
@@ -44,7 +48,20 @@
|
|
|
44
48
|
* ```
|
|
45
49
|
*/
|
|
46
50
|
import React, { createContext, useContext, useRef, useEffect, useState, useCallback, } from 'react';
|
|
47
|
-
|
|
51
|
+
// SSR detection - Excalibur requires browser APIs
|
|
52
|
+
const isBrowser = typeof window !== 'undefined';
|
|
53
|
+
// Only import Excalibur on the client side
|
|
54
|
+
// These will be undefined during SSR
|
|
55
|
+
let Engine;
|
|
56
|
+
let DisplayMode;
|
|
57
|
+
let ExColor;
|
|
58
|
+
if (isBrowser) {
|
|
59
|
+
// Dynamic require on client only
|
|
60
|
+
const ex = require('excalibur');
|
|
61
|
+
Engine = ex.Engine;
|
|
62
|
+
DisplayMode = ex.DisplayMode;
|
|
63
|
+
ExColor = ex.Color;
|
|
64
|
+
}
|
|
48
65
|
// Re-export Excalibur classes for convenience
|
|
49
66
|
// Core
|
|
50
67
|
export { Actor, Vector, Color, Engine, Scene, Timer, Trigger, Label } from 'excalibur';
|
|
@@ -77,10 +94,15 @@ export { coroutine } from 'excalibur';
|
|
|
77
94
|
// Utilities
|
|
78
95
|
export { Logger, LogLevel } from 'excalibur';
|
|
79
96
|
/**
|
|
80
|
-
* Game dimensions -
|
|
97
|
+
* Game dimensions - optimized for mobile performance (9:16 aspect ratio)
|
|
98
|
+
* Full page view: 540x960 (half of Full HD)
|
|
99
|
+
* Tile view: 360x640 (optimized for 256x554 tile container)
|
|
81
100
|
*/
|
|
82
|
-
export const GAME_WIDTH =
|
|
83
|
-
export const GAME_HEIGHT =
|
|
101
|
+
export const GAME_WIDTH = 540;
|
|
102
|
+
export const GAME_HEIGHT = 960;
|
|
103
|
+
/** Tile view dimensions - use these when rendering in tile (256x554) container */
|
|
104
|
+
export const TILE_GAME_WIDTH = 360;
|
|
105
|
+
export const TILE_GAME_HEIGHT = 640;
|
|
84
106
|
const ExcaliburContext = createContext(null);
|
|
85
107
|
/**
|
|
86
108
|
* Hook to get the Excalibur Engine
|
|
@@ -123,20 +145,38 @@ export function useGameLoop(callback, enabled = true) {
|
|
|
123
145
|
*
|
|
124
146
|
* Creates an Excalibur Engine and provides it via context.
|
|
125
147
|
* Children can use useEngine() to access the engine and add actors/entities.
|
|
148
|
+
*
|
|
149
|
+
* This component handles SSR gracefully by rendering a loading placeholder
|
|
150
|
+
* until the client-side Excalibur engine is ready.
|
|
126
151
|
*/
|
|
127
|
-
export function ExcaliburGame({ children, width = GAME_WIDTH, height = GAME_HEIGHT, backgroundColor = '#000000', displayMode
|
|
152
|
+
export function ExcaliburGame({ children, width = GAME_WIDTH, height = GAME_HEIGHT, backgroundColor = '#000000', displayMode, options = {}, paused = false, onMount, }) {
|
|
128
153
|
const containerRef = useRef(null);
|
|
129
154
|
const engineRef = useRef(null);
|
|
130
155
|
const updateCallbacksRef = useRef(new Set());
|
|
131
156
|
const [isReady, setIsReady] = useState(false);
|
|
157
|
+
// SSR guard - render loading placeholder on server
|
|
158
|
+
if (!isBrowser || !Engine || !DisplayMode || !ExColor) {
|
|
159
|
+
return (React.createElement("div", { style: {
|
|
160
|
+
width: '100%',
|
|
161
|
+
height: '100dvh',
|
|
162
|
+
overflow: 'hidden',
|
|
163
|
+
backgroundColor,
|
|
164
|
+
display: 'flex',
|
|
165
|
+
alignItems: 'center',
|
|
166
|
+
justifyContent: 'center'
|
|
167
|
+
} },
|
|
168
|
+
React.createElement("div", { style: { color: '#fff', fontSize: '18px' } }, "Loading game...")));
|
|
169
|
+
}
|
|
170
|
+
// Use default display mode (must be after SSR check since DisplayMode is undefined on server)
|
|
171
|
+
const resolvedDisplayMode = displayMode ?? DisplayMode.FitContainerAndFill;
|
|
132
172
|
// Create Excalibur Engine
|
|
133
173
|
useEffect(() => {
|
|
134
|
-
if (!containerRef.current)
|
|
174
|
+
if (!containerRef.current || !Engine || !ExColor)
|
|
135
175
|
return;
|
|
136
176
|
const engine = new Engine({
|
|
137
177
|
width,
|
|
138
178
|
height,
|
|
139
|
-
displayMode,
|
|
179
|
+
displayMode: resolvedDisplayMode,
|
|
140
180
|
backgroundColor: ExColor.fromHex(backgroundColor),
|
|
141
181
|
canvasElementId: undefined,
|
|
142
182
|
antialiasing: options.antialiasing ?? true,
|