From 1c313b4f64b2e15004376628f0566ba0d5297a24 Mon Sep 17 00:00:00 2001 From: York Date: Mon, 20 Jan 2025 00:41:58 -0800 Subject: [PATCH] update: GameConfig docs --- src/game/nlcore/gameTypes.ts | 55 ++++++++++++++++++++++++++++++++---- 1 file changed, 50 insertions(+), 5 deletions(-) diff --git a/src/game/nlcore/gameTypes.ts b/src/game/nlcore/gameTypes.ts index c1147fb..7f5c71f 100644 --- a/src/game/nlcore/gameTypes.ts +++ b/src/game/nlcore/gameTypes.ts @@ -24,99 +24,129 @@ export interface SavedGame { } export type GameConfig = { + /** + * Config for the player + */ player: { /** * The id of the container element for the game + * @default "__narraleaf_content" */ contentContainerId: string; /** * The aspect ratio of the game * Ex: 16/9, 4/3, 1/1 + * @default 16/9 */ aspectRatio: number; /** * The minimum width and height of the player in pixels + * @default 800 */ minWidth: number; /** * The minimum width and height of the player in pixels + * @default 450 */ minHeight: number; /** * Base width of the player in pixels, Image scale will be calculated based on this value * * For 16/9, the recommended value is 1920 + * @default 1920 */ width: number; /** * Base height of the player in pixels, Image scale will be calculated based on this value * * For 16/9, the recommended value is 1080 + * @default 1080 */ height: number; /** * When the player presses one of these keys, the game will skip the current action * * See [Key_Values](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) + * @default ["Control"] */ skipKey: React.KeyboardEvent["key"][]; /** * The interval in milliseconds between each skip action. * ex: 100 ms means the player can skip 10 actions per second. * higher value means faster skipping. + * @default 100 */ skipInterval: number; /** - * The interval in milliseconds between each ratio update. + * The debounced interval in milliseconds for updating the aspect ratio + * + * Set to 0 to update the ratio immediately on every resize event. + * @default 50 */ ratioUpdateInterval: number; /** - * The game will preload the image with this delay in milliseconds + * The game will preload the image with this delay between each preload task + * + * A single preload task may contain {@link GameConfig.player.preloadConcurrency} images + * @default 100 */ preloadDelay: number; /** * Maximum number of images to preload at the same time + * @default 5 */ preloadConcurrency: number; /** * Wait for the images to load before showing the game + * @default true */ waitForPreload: boolean; /** * Preload all possible images in the scene * * Enabling this may have a performance impact but is better for the user experience + * @default true */ preloadAllImages: boolean; /** * Force the game to clear the cache when the scene changes + * @default false */ forceClearCache: boolean; /** * The number of actions will be predicted and preloaded + * @default 10 */ maxPreloadActions: number; /** * Src of the cursor image, if null, the game will show the default cursor + * @default null */ cursor: string | null; /** * Cursor width in pixels + * @default 30 */ cursorWidth: number; /** * Cursor height in pixels + * @default 30 */ cursorHeight: number; /** - * Show overflowed content + * Show overflowed content on player components + * @default false */ showOverflow: boolean; /** * Max history size for the page router + * @default 10 */ maxRouterHistory: number; }; + /** + * Config for the game elements + */ elements: { /** * For all `Character` elements @@ -126,12 +156,13 @@ export type GameConfig = { * When the player presses one of these keys, the game will show the next sentence * * See [Key_Values](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) + * @default [" "] */ nextKey: React.KeyboardEvent["key"][]; /** * The speed of the text effects in milliseconds. * higher value means slower text effect. - * default: 50 + * @default 50 */ textInterval: number; use: SayComponent; @@ -139,10 +170,14 @@ export type GameConfig = { * If true, the game will scale the dialog to fit the screen * * Text will look smaller when this is enabled + * @default true */ useAspectScale: boolean; /** * The delay in milliseconds before the game automatically shows the next sentence + * + * Only works when the player preference "autoForward" is enabled + * @default 3000 */ autoForwardDelay: number; }, @@ -152,10 +187,12 @@ export type GameConfig = { img: { /** * If true, when you press [GameConfig.player.skipKey], the game will skip the image transform + * @default true */ allowSkipTransform: boolean; /** * If true, when you press [GameConfig.player.skipKey], the game will skip the image transition + * @default true */ allowSkipTransition: boolean; }, @@ -171,38 +208,45 @@ export type GameConfig = { background: { /** * If true, when you press [GameConfig.player.skipKey], the game will skip the background transform + * @default true */ allowSkipTransform: boolean; /** * If true, when you press [GameConfig.player.skipKey], the game will skip the background transition + * @default false */ allowSkipTransition: boolean; }, text: { /** * If true, when you press [GameConfig.player.skipKey], the game will skip the text transform + * @default true */ allowSkipTransform: boolean; /** * If true, when you press [GameConfig.player.skipKey], the game will skip the text transition + * @default true */ allowSkipTransition: boolean; /** * Base width of the dialog in pixels * * For 16/9, the recommended value is 1920 + * @default 1920 */ width: number; /** * Base height of the dialog in pixels * - * For 16/9, the recommended value is 1080 * 0.2 + * For 16/9, the recommended value is 1080 * 0.2 (20% of the screen height) + * @default 1080 * 0.2 */ height: number; }, layers: { /** * If true, when you press [GameConfig.player.skipKey], the game will skip the text transform + * @default true */ allowSkipTransform: boolean; }, @@ -243,6 +287,7 @@ export type GameConfig = { debug: boolean; /** * Log level for the logger + * Set to true to enable all logs */ logger: { log: boolean;