littlejsengine
Version:
LittleJS - Tiny and Fast HTML5 Game Engine
1,153 lines (1,152 loc) • 221 kB
TypeScript
declare module "littlejsengine" {
/**
* - Update or render function for a plugin
*/
export type PluginCallback = () => any;
/**
* - Called after the engine starts, can be async
*/
export type GameInitCallback = () => void | Promise<void>;
/**
* - Update or render function for the game
*/
export type GameCallback = () => any;
/**
* - Function that processes an object
*/
export type ObjectCallbackFunction = (object: EngineObject) => any;
/**
* - Checks if a position is colliding
*/
export type LineTestFunction = (pos: Vector2) => any;
/**
* - A function that draws to a 2D canvas context
*/
export type Canvas2DDrawFunction = (context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => any;
/**
* - Function called when a sound ends
*/
export type AudioEndedCallback = (source: AudioBufferSourceNode) => any;
/**
* - Function to handle a tile collision test
*/
export type TileCollisionCallback = (tileData: number, pos: Vector2) => any;
/**
* - Function that processes a medal
*/
export type MedalCallbackFunction = (medal: Medal) => any;
/**
* - Function that processes a particle
*/
export type ParticleCallback = (particle: Particle) => any;
/**
* - Collide callback for particles
*/
export type ParticleCollideCallback = (particle: Particle, tileData: number, pos: Vector2) => any;
/**
* LittleJS - The Tiny Fast JavaScript Game Engine
* MIT License - Copyright 2021 Frank Force
*
* Engine Features
* - Object oriented system with base class engine object
* - Base class object handles update, physics, collision, rendering, etc
* - Engine helper classes and functions like Vector2, Color, and Timer
* - Super fast rendering system for tile sheets
* - Sound effects audio with zzfx and music with zzfxm
* - Input processing system with gamepad and touchscreen support
* - Tile layer rendering and collision system
* - Particle effect system
* - Medal system tracks and displays achievements
* - Debug tools and debug rendering system
* - Post processing effects
* - Call engineInit() to start it up!
* @namespace Engine
*/
/** Name of engine
* @type {string}
* @default
* @memberof Engine */
export const engineName: string;
/** Version of engine
* @type {string}
* @default
* @memberof Engine */
export const engineVersion: string;
/** Frames per second to update
* @type {number}
* @default
* @memberof Engine */
export const frameRate: number;
/** How many seconds each frame lasts, engine uses a fixed time step
* @type {number}
* @default 1/60
* @memberof Engine */
export const timeDelta: number;
/** Array containing all engine objects
* @type {Array<EngineObject>}
* @memberof Engine */
export let engineObjects: Array<EngineObject>;
/** Current update frame, used to calculate time
* @type {number}
* @memberof Engine */
export let frame: number;
/** Current engine time since start in seconds
* @type {number}
* @memberof Engine */
export let time: number;
/** Actual clock time since start in seconds (not affected by pause or frame rate clamping)
* @type {number}
* @memberof Engine */
export let timeReal: number;
/** Is the game paused? Causes time and objects to not be updated
* @type {boolean}
* @default false
* @memberof Engine */
export let paused: boolean;
/** Get if game is paused
* @return {boolean}
* @memberof Engine */
export function getPaused(): boolean;
/** Set if game is paused
* @param {boolean} [isPaused]
* @memberof Engine */
export function setPaused(isPaused?: boolean): void;
/**
* @callback GameInitCallback - Called after the engine starts, can be async
* @return {void|Promise<void>}
* @memberof Engine
*/
/**
* @callback GameCallback - Update or render function for the game
* @memberof Engine
*/
/** Startup LittleJS engine with your callback functions
* @param {GameInitCallback} gameInit - Called once after the engine starts up, can be async for loading
* @param {GameCallback} gameUpdate - Called every frame before objects are updated (60fps), use for game logic
* @param {GameCallback} gameUpdatePost - Called after physics and objects are updated, even when paused, use for UI updates
* @param {GameCallback} gameRender - Called before objects are rendered, use for drawing backgrounds/world elements
* @param {GameCallback} gameRenderPost - Called after objects are rendered, use for drawing UI/overlays
* @param {Array<string>} [imageSources=[]] - List of image file paths to preload (e.g., ['player.png', 'tiles.png'])
* @param {HTMLElement} [rootElement] - Root DOM element to attach canvas to, defaults to document.body
* @example
* // Basic engine startup
* engineInit(
* ()=> { LOG('Game initialized!'); }, // gameInit
* ()=> { updateGameLogic(); }, // gameUpdate
* ()=> { updateUI(); }, // gameUpdatePost
* ()=> { drawBackground(); }, // gameRender
* ()=> { drawHUD(); }, // gameRenderPost
* ['tiles.png', 'tilesLevel.png'] // images to load
* );
* @memberof Engine */
export function engineInit(gameInit: GameInitCallback, gameUpdate: GameCallback, gameUpdatePost: GameCallback, gameRender: GameCallback, gameRenderPost: GameCallback, imageSources?: Array<string>, rootElement?: HTMLElement): Promise<void>;
/** Update each engine object, remove destroyed objects, and update time
* can be called manually if objects need to be updated outside of main loop
* @memberof Engine */
export function engineObjectsUpdate(): void;
/** Destroy and remove all objects
* - This can be used to clear out all objects when restarting a level
* - Objects can override their destroy function to do cleanup or stick around
* @param {boolean} [immediate] - should attached effects be allowed to die off?
* @memberof Engine */
export function engineObjectsDestroy(immediate?: boolean): void;
/** Collects all object within a given area
* @param {Vector2} [pos] - Center of test area, or undefined for all objects
* @param {Vector2|number} [size] - Radius of circle if float, rectangle size if Vector2
* @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
* @return {Array<EngineObject>} - List of collected objects
* @memberof Engine */
export function engineObjectsCollect(pos?: Vector2, size?: Vector2 | number, objects?: Array<EngineObject>): Array<EngineObject>;
/**
* @callback ObjectCallbackFunction - Function that processes an object
* @param {EngineObject} object
* @memberof Engine
*/
/** Triggers a callback for each object within a given area
* @param {Vector2} [pos] - Center of test area, or undefined for all objects
* @param {Vector2|number} [size] - Radius of circle if float, rectangle size if Vector2
* @param {ObjectCallbackFunction} [callbackFunction] - Calls this function on every object that passes the test
* @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
* @memberof Engine */
export function engineObjectsCallback(pos?: Vector2, size?: Vector2 | number, callbackFunction?: ObjectCallbackFunction, objects?: Array<EngineObject>): void;
/** Return a list of objects intersecting a ray
* @param {Vector2} start
* @param {Vector2} end
* @param {Array<EngineObject>} [objects=engineObjects] - List of objects to check
* @return {Array<EngineObject>} - List of objects hit
* @memberof Engine */
export function engineObjectsRaycast(start: Vector2, end: Vector2, objects?: Array<EngineObject>): Array<EngineObject>;
/**
* @callback PluginCallback - Update or render function for a plugin
* @memberof Engine
*/
/** Add a new update function for a plugin
* @param {PluginCallback} [update]
* @param {PluginCallback} [render]
* @param {PluginCallback} [glContextLost]
* @param {PluginCallback} [glContextRestored]
* @memberof Engine */
export function engineAddPlugin(update?: PluginCallback, render?: PluginCallback, glContextLost?: PluginCallback, glContextRestored?: PluginCallback): void;
/**
* LittleJS Debug System
* - Press Esc to show debug overlay with mouse pick
* - Number keys toggle debug functions
* - +/- apply time scale
* - Debug primitive rendering
* - Save a 2d canvas as a png image
* @namespace Debug
*/
/** True if debug is enabled
* @type {boolean}
* @default
* @memberof Debug */
export const debug: boolean;
/** True if the debug overlay is active, always false in release builds
* @type {boolean}
* @default
* @memberof Debug */
export let debugOverlay: boolean;
/** True if watermark with FPS should be shown, false in release builds
* @type {boolean}
* @default
* @memberof Debug */
export let debugWatermark: boolean;
/** Asserts if the expression is false, does nothing in release builds
* Halts execution if the assert fails and throws an error
* @param {boolean} assert
* @param {...Object} output - error message output
* @memberof Debug */
export function ASSERT(assert: boolean, ...output: any[]): void;
/** Log to console if debug is enabled, does nothing in release builds
* @param {...Object} output - message output
* @memberof Debug */
export function LOG(...output: any[]): void;
/** Draw a debug rectangle in world space
* @param {Vector2} pos
* @param {Vector2} [size=vec2(0)]
* @param {Color|string} [color]
* @param {number} [time]
* @param {number} [angle]
* @param {boolean} [fill]
* @param {boolean} [screenSpace]
* @memberof Debug */
export function debugRect(pos: Vector2, size?: Vector2, color?: Color | string, time?: number, angle?: number, fill?: boolean, screenSpace?: boolean): void;
/** Draw a debug poly in world space
* @param {Vector2} pos
* @param {Array<Vector2>} points
* @param {Color|string} [color]
* @param {number} [time]
* @param {number} [angle]
* @param {boolean} [fill]
* @param {boolean} [screenSpace]
* @memberof Debug */
export function debugPoly(pos: Vector2, points: Array<Vector2>, color?: Color | string, time?: number, angle?: number, fill?: boolean, screenSpace?: boolean): void;
/** Draw a debug circle in world space
* @param {Vector2} pos
* @param {number} [size] - diameter
* @param {Color|string} [color]
* @param {number} [time]
* @param {boolean} [fill]
* @param {boolean} [screenSpace]
* @memberof Debug */
export function debugCircle(pos: Vector2, size?: number, color?: Color | string, time?: number, fill?: boolean, screenSpace?: boolean): void;
/** Draw a debug point in world space
* @param {Vector2} pos
* @param {Color|string} [color]
* @param {number} [time]
* @param {number} [angle]
* @param {boolean} [screenSpace]
* @memberof Debug */
export function debugPoint(pos: Vector2, color?: Color | string, time?: number, angle?: number, screenSpace?: boolean): void;
/** Draw a debug line in world space
* @param {Vector2} posA
* @param {Vector2} posB
* @param {Color|string} [color]
* @param {number} [width]
* @param {number} [time]
* @param {boolean} [screenSpace]
* @memberof Debug */
export function debugLine(posA: Vector2, posB: Vector2, color?: Color | string, width?: number, time?: number, screenSpace?: boolean): void;
/** Draw a debug combined axis aligned bounding box in world space
* @param {Vector2} posA
* @param {Vector2} sizeA
* @param {Vector2} posB
* @param {Vector2} sizeB
* @param {Color|string} [color]
* @param {number} [time]
* @param {boolean} [screenSpace]
* @memberof Debug */
export function debugOverlap(posA: Vector2, sizeA: Vector2, posB: Vector2, sizeB: Vector2, color?: Color | string, time?: number, screenSpace?: boolean): void;
/** Draw a debug axis aligned bounding box in world space
* @param {string|number} text
* @param {Vector2} pos
* @param {number} [size]
* @param {Color|string} [color]
* @param {number} [time]
* @param {number} [angle]
* @param {string} [font]
* @param {boolean} [screenSpace]
* @memberof Debug */
export function debugText(text: string | number, pos: Vector2, size?: number, color?: Color | string, time?: number, angle?: number, font?: string, screenSpace?: boolean): void;
/** Clear all debug primitives in the list
* @memberof Debug */
export function debugClear(): void;
/** Trigger debug system to take a screenshot
* @memberof Debug */
export function debugScreenshot(): void;
/** Breaks on all asserts/errors, hides the canvas, and shows message in plain text
* This is a good function to call at the start of your game to catch all errors
* In release builds this function has no effect
* @memberof Debug */
export function debugShowErrors(): void;
/** Start capturing video
* @memberof Debug */
export function debugVideoCaptureStart(): void;
/** Stop capturing video and save to disk
* @memberof Debug */
export function debugVideoCaptureStop(): void;
/** Check if video capture is active
* @memberof Debug */
export function debugVideoCaptureIsActive(): boolean;
/**
* LittleJS Engine Settings
* - All settings for the engine are here
* @namespace Settings
*/
/** Position of camera in world space
* @type {Vector2}
* @default Vector2()
* @memberof Settings */
export let cameraPos: Vector2;
/** Rotation angle of camera in world space
* @type {number}
* @default
* @memberof Settings */
export let cameraAngle: number;
/** Scale of camera in world space
* @type {number}
* @default
* @memberof Settings */
export let cameraScale: number;
/** Enable applying color to tiles when using canvas2d
* - This is slower but should be the same as WebGL rendering
* @type {boolean}
* @default
* @memberof Settings */
export let canvasColorTiles: boolean;
/** Color to clear the canvas to before render, does not clear if alpha is 0
* @type {Color}
* @memberof Draw */
export let canvasClearColor: Color;
/** The max size of the canvas, centered if window is larger
* @type {Vector2}
* @default Vector2(1920,1080)
* @memberof Settings */
export let canvasMaxSize: Vector2;
/** Minimum aspect ratio of the canvas (width/height), unused if 0
* Can be used with canvasMaxAspect to limit aspect ratio
* @type {number}
* @default
* @memberof Settings */
export let canvasMinAspect: number;
/** Maximum aspect ratio of the canvas (width/height), unused if 0
* Can be used with canvasMinAspect to limit aspect ratio
* @type {number}
* @default
* @memberof Settings */
export let canvasMaxAspect: number;
/** Fixed size of the canvas, if enabled canvas size never changes
* - you may also need to set mainCanvasSize if using screen space coords in startup
* @type {Vector2}
* @default Vector2()
* @memberof Settings */
export let canvasFixedSize: Vector2;
/** Use nearest canvas scaling for more pixelated look
* - If enabled sets css image-rendering:pixelated
* @type {boolean}
* @default
* @memberof Settings */
export let canvasPixelated: boolean;
/** Disables texture filtering for crisper pixel art
* @type {boolean}
* @default
* @memberof Settings */
export let tilesPixelated: boolean;
/** Default font used for text rendering
* @type {string}
* @default
* @memberof Settings */
export let fontDefault: string;
/** Enable to show the LittleJS splash screen on startup
* @type {boolean}
* @default
* @memberof Settings */
export let showSplashScreen: boolean;
/** Disables all rendering, audio, and input for servers
* @type {boolean}
* @default
* @memberof Settings */
export let headlessMode: boolean;
/** Default size of tiles in pixels
* @type {Vector2}
* @default Vector2(16,16)
* @memberof Settings */
export let tileDefaultSize: Vector2;
/** Default padding pixels around tiles
* @type {number}
* @default
* @memberof Settings */
export let tileDefaultPadding: number;
/** Default amount of pixels smaller to draw tiles to prevent neighbor bleeding
* @type {number}
* @default
* @memberof Settings */
export let tileDefaultBleed: number;
/** Enable physics solver for collisions between objects
* @type {boolean}
* @default
* @memberof Settings */
export let enablePhysicsSolver: boolean;
/** Default object mass for collision calculations (how heavy objects are)
* @type {number}
* @default
* @memberof Settings */
export let objectDefaultMass: number;
/** How much to slow velocity by each frame (0-1)
* @type {number}
* @default
* @memberof Settings */
export let objectDefaultDamping: number;
/** How much to slow angular velocity each frame (0-1)
* @type {number}
* @default
* @memberof Settings */
export let objectDefaultAngleDamping: number;
/** How much to bounce when a collision occurs (0-1)
* @type {number}
* @default
* @memberof Settings */
export let objectDefaultRestitution: number;
/** How much to slow when touching (0-1)
* @type {number}
* @default
* @memberof Settings */
export let objectDefaultFriction: number;
/** Clamp max speed to avoid fast objects missing collisions
* @type {number}
* @default
* @memberof Settings */
export let objectMaxSpeed: number;
/** How much gravity to apply to objects, negative Y is down
* @type {Vector2}
* @default
* @memberof Settings */
export let gravity: Vector2;
/** Scales emit rate of particles, useful for low graphics mode (0 disables particle emitters)
* @type {number}
* @default
* @memberof Settings */
export let particleEmitRateScale: number;
/** Enable WebGL accelerated rendering
* @type {boolean}
* @default
* @memberof Settings */
export let glEnable: boolean;
/** Should gamepads be allowed
* @type {boolean}
* @default
* @memberof Settings */
export let gamepadsEnable: boolean;
/** If true, the dpad input is also routed to the left analog stick (for better accessibility)
* @type {boolean}
* @default
* @memberof Settings */
export let gamepadDirectionEmulateStick: boolean;
/** If true the WASD keys are also routed to the direction keys (for better accessibility)
* @type {boolean}
* @default
* @memberof Settings */
export let inputWASDEmulateDirection: boolean;
/** True if touch gamepad should appear on mobile devices
* - Supports left analog stick, 4 face buttons and start button (button 9)
* @type {boolean}
* @default
* @memberof Settings */
export let touchGamepadEnable: boolean;
/** True if touch gamepad should have start button in the center
* - When the game is paused, any touch will press the button
* - This can function as a way to pause/unpause the game
* @type {boolean}
* @default
* @memberof Settings */
export let touchGamepadCenterButton: boolean;
/** True if touch gamepad should be analog stick or false to use if 8 way dpad
* @type {boolean}
* @default
* @memberof Settings */
export let touchGamepadAnalog: boolean;
/** Size of virtual gamepad for touch devices in pixels
* @type {number}
* @default
* @memberof Settings */
export let touchGamepadSize: number;
/** Transparency of touch gamepad overlay
* @type {number}
* @default
* @memberof Settings */
export let touchGamepadAlpha: number;
/** Allow vibration hardware if it exists
* @type {boolean}
* @default
* @memberof Settings */
export let vibrateEnable: boolean;
/** All audio code can be disabled and removed from build
* @type {boolean}
* @default
* @memberof Settings */
export let soundEnable: boolean;
/** Volume scale to apply to all sound, music and speech
* @type {number}
* @default
* @memberof Settings */
export let soundVolume: number;
/** Default range where sound no longer plays
* @type {number}
* @default
* @memberof Settings */
export let soundDefaultRange: number;
/** Default range percent to start tapering off sound (0-1)
* @type {number}
* @default
* @memberof Settings */
export let soundDefaultTaper: number;
/** How long to show medals for in seconds
* @type {number}
* @default
* @memberof Settings */
export let medalDisplayTime: number;
/** How quickly to slide on/off medals in seconds
* @type {number}
* @default
* @memberof Settings */
export let medalDisplaySlideTime: number;
/** Size of medal display
* @type {Vector2}
* @default Vector2(640,80)
* @memberof Settings */
export let medalDisplaySize: Vector2;
/** Set position of camera in world space
* @param {Vector2} pos
* @memberof Settings */
export function setCameraPos(pos: Vector2): void;
/** Set angle of camera in world space
* @param {number} angle
* @memberof Settings */
export function setCameraAngle(angle: number): void;
/** Set scale of camera in world space
* @param {number} scale
* @memberof Settings */
export function setCameraScale(scale: number): void;
/** Set if tiles should be colorized when using canvas2d
* This can be slower but results should look nearly identical to WebGL rendering
* It can be enabled/disabled at any time
* Optimized for performance, and will use faster method if color is white or untextured
* @param {boolean} colorTiles
* @memberof Settings */
export function setCanvasColorTiles(colorTiles: boolean): void;
/** Set color to clear the canvas to before render, does not clear if alpha is 0
* @param {Color} color
* @memberof Settings */
export function setCanvasClearColor(color: Color): void;
/** Set max size of the canvas
* @param {Vector2} size
* @memberof Settings */
export function setCanvasMaxSize(size: Vector2): void;
/** Set minimum aspect ratio of the canvas (width/height), unused if 0
* @param {number} aspect
* @memberof Settings */
export function setCanvasMinAspect(aspect: number): void;
/** Set maximum aspect ratio of the canvas (width/height), unused if 0
* @param {number} aspect
* @memberof Settings */
export function setCanvasMaxAspect(aspect: number): void;
/** Set fixed size of the canvas
* @param {Vector2} size
* @memberof Settings */
export function setCanvasFixedSize(size: Vector2): void;
/** Use nearest scaling algorithm for canvas for more pixelated look
* @param {boolean} pixelated
* @memberof Settings */
export function setCanvasPixelated(pixelated: boolean): void;
/** Disables texture filtering for crisper pixel art
* @param {boolean} pixelated
* @memberof Settings */
export function setTilesPixelated(pixelated: boolean): void;
/** Set default font used for text rendering
* @param {string} font
* @memberof Settings */
export function setFontDefault(font: string): void;
/** Set if the LittleJS splash screen should be shown on startup
* @param {boolean} show
* @memberof Settings */
export function setShowSplashScreen(show: boolean): void;
/** Set to disable rendering, audio, and input for servers
* @param {boolean} headless
* @memberof Settings */
export function setHeadlessMode(headless: boolean): void;
/** Set if WebGL rendering is enabled
* @param {boolean} enable
* @memberof Settings */
export function setGLEnable(enable: boolean): void;
/** Set default size of tiles in pixels
* @param {Vector2} size
* @memberof Settings */
export function setTileDefaultSize(size: Vector2): void;
/** Default padding pixels around tiles
* @param {number} padding
* @memberof Settings */
export function setTileDefaultPadding(padding: number): void;
/** Default amount of pixels smaller to draw tiles to prevent neighbor bleeding
* @param {number} bleed
* @memberof Settings */
export function setTileDefaultBleed(bleed: number): void;
/** Set if collisions between objects are enabled
* @param {boolean} enable
* @memberof Settings */
export function setEnablePhysicsSolver(enable: boolean): void;
/** Set default object mass for collision calculations
* @param {number} mass
* @memberof Settings */
export function setObjectDefaultMass(mass: number): void;
/** Set how much to slow velocity by each frame
* @param {number} damp
* @memberof Settings */
export function setObjectDefaultDamping(damp: number): void;
/** Set how much to slow angular velocity each frame
* @param {number} damp
* @memberof Settings */
export function setObjectDefaultAngleDamping(damp: number): void;
/** Set how much to bounce when a collision occurs
* @param {number} restitution
* @memberof Settings */
export function setObjectDefaultRestitution(restitution: number): void;
/** Set how much to slow when touching
* @param {number} friction
* @memberof Settings */
export function setObjectDefaultFriction(friction: number): void;
/** Set max speed to avoid fast objects missing collisions
* @param {number} speed
* @memberof Settings */
export function setObjectMaxSpeed(speed: number): void;
/** Set how much gravity to apply to objects
* @param {Vector2} newGravity
* @memberof Settings */
export function setGravity(newGravity: Vector2): void;
/** Set to scales emit rate of particles
* @param {number} scale
* @memberof Settings */
export function setParticleEmitRateScale(scale: number): void;
/** Set if touch input is allowed
* @param {boolean} enable
* @memberof Settings */
export function setTouchInputEnable(enable: boolean): void;
/** Set if gamepads are enabled
* @param {boolean} enable
* @memberof Settings */
export function setGamepadsEnable(enable: boolean): void;
/** Set if the dpad input is also routed to the left analog stick
* @param {boolean} enable
* @memberof Settings */
export function setGamepadDirectionEmulateStick(enable: boolean): void;
/** Set if true the WASD keys are also routed to the direction keys
* @param {boolean} enable
* @memberof Settings */
export function setInputWASDEmulateDirection(enable: boolean): void;
/** Set if touch gamepad should appear on mobile devices
* @param {boolean} enable
* @memberof Settings */
export function setTouchGamepadEnable(enable: boolean): void;
/** True if touch gamepad should have start button in the center
* - This can function as a way to pause/unpause the game
* @param {boolean} enable
* @memberof Settings */
export function setTouchGamepadCenterButton(enable: boolean): void;
/** Set number of buttons on touch gamepad (0-4), if 1 also acts as right analog stick
* @param {number} count
* @memberof Settings */
export function setTouchGamepadButtonCount(count: number): void;
/** Set if touch gamepad should be analog stick or 8 way dpad
* @param {boolean} analog
* @memberof Settings */
export function setTouchGamepadAnalog(analog: boolean): void;
/** Set size of virtual gamepad for touch devices in pixels
* @param {number} size
* @memberof Settings */
export function setTouchGamepadSize(size: number): void;
/** Set transparency of touch gamepad overlay
* @param {number} alpha
* @memberof Settings */
export function setTouchGamepadAlpha(alpha: number): void;
/** Set to allow vibration hardware if it exists
* @param {boolean} enable
* @memberof Settings */
export function setVibrateEnable(enable: boolean): void;
/** Set to disable all audio code
* @param {boolean} enable
* @memberof Settings */
export function setSoundEnable(enable: boolean): void;
/** Set volume scale to apply to all sound, music and speech
* @param {number} volume
* @memberof Settings */
export function setSoundVolume(volume: number): void;
/** Set default range where sound no longer plays
* @param {number} range
* @memberof Settings */
export function setSoundDefaultRange(range: number): void;
/** Set default range percent to start tapering off sound
* @param {number} taper
* @memberof Settings */
export function setSoundDefaultTaper(taper: number): void;
/** Set how long to show medals for in seconds
* @param {number} time
* @memberof Settings */
export function setMedalDisplayTime(time: number): void;
/** Set how quickly to slide on/off medals in seconds
* @param {number} time
* @memberof Settings */
export function setMedalDisplaySlideTime(time: number): void;
/** Set size of medal display
* @param {Vector2} size
* @memberof Settings */
export function setMedalDisplaySize(size: Vector2): void;
/** Set to stop medals from being unlockable
* @param {boolean} preventUnlock
* @memberof Settings */
export function setMedalsPreventUnlock(preventUnlock: boolean): void;
/** Set if watermark with FPS should be shown
* @param {boolean} show
* @memberof Debug */
export function setDebugWatermark(show: boolean): void;
/** Set key code used to toggle debug mode, Esc by default
* @param {string} key
* @memberof Debug */
export function setDebugKey(key: string): void;
/**
* LittleJS Math Classes and Functions
* - General purpose math library
* - RandomGenerator - seeded random number generator
* - Vector2 - fast, simple, easy 2D vector class
* - Color - holds a rgba color with math functions
* @namespace Math
*/
/** The value of PI
* @type {number}
* @default Math.PI
* @memberof Math */
export const PI: number;
/** Returns absolute value of value passed in
* @param {number} x
* @return {number}
* @memberof Math */
export const abs: (x: number) => number;
/** Returns floored value of value passed in
* @param {number} x
* @return {number}
* @memberof Math */
export const floor: (x: number) => number;
/** Returns ceiled value of value passed in
* @param {number} x
* @return {number}
* @memberof Math */
export const ceil: (x: number) => number;
/** Returns rounded value passed in
* @param {number} x
* @return {number}
* @memberof Math */
export const round: (x: number) => number;
/** Returns lowest value passed in
* @param {...number} values
* @return {number}
* @memberof Math */
export const min: (...values: number[]) => number;
/** Returns highest value passed in
* @param {...number} values
* @return {number}
* @memberof Math */
export const max: (...values: number[]) => number;
/** Returns the sign of value passed in
* @param {number} x
* @return {number}
* @memberof Math */
export const sign: (x: number) => number;
/** Returns hypotenuse of values passed in
* @param {...number} values
* @return {number}
* @memberof Math */
export const hypot: (...values: number[]) => number;
/** Returns log2 of value passed in
* @param {number} x
* @return {number}
* @memberof Math */
export const log2: (x: number) => number;
/** Returns sin of value passed in
* @param {number} x
* @return {number}
* @memberof Math */
export const sin: (x: number) => number;
/** Returns cos of value passed in
* @param {number} x
* @return {number}
* @memberof Math */
export const cos: (x: number) => number;
/** Returns tan of value passed in
* @param {number} x
* @return {number}
* @memberof Math */
export const tan: (x: number) => number;
/** Returns atan2 of values passed in
* @param {number} y
* @param {number} x
* @return {number}
* @memberof Math */
export const atan2: (y: number, x: number) => number;
/** Returns first parm modulo the second param, but adjusted so negative numbers work as expected
* @param {number} dividend
* @param {number} [divisor]
* @return {number}
* @memberof Math */
export function mod(dividend: number, divisor?: number): number;
/** Clamps the value between max and min
* @param {number} value
* @param {number} [min]
* @param {number} [max]
* @return {number}
* @memberof Math */
export function clamp(value: number, min?: number, max?: number): number;
/** Returns what percentage the value is between valueA and valueB
* @param {number} value
* @param {number} valueA
* @param {number} valueB
* @return {number}
* @memberof Math */
export function percent(value: number, valueA: number, valueB: number): number;
/** Returns signed wrapped distance between the two values passed in
* @param {number} valueA
* @param {number} valueB
* @param {number} [wrapSize]
* @return {number}
* @memberof Math */
export function distanceWrap(valueA: number, valueB: number, wrapSize?: number): number;
/** Linearly interpolates between values passed in with wrapping
* @param {number} valueA
* @param {number} valueB
* @param {number} percent
* @param {number} [wrapSize]
* @return {number}
* @memberof Math */
export function lerpWrap(valueA: number, valueB: number, percent: number, wrapSize?: number): number;
/** Returns signed wrapped distance between the two angles passed in
* @param {number} angleA
* @param {number} angleB
* @return {number}
* @memberof Math */
export function distanceAngle(angleA: number, angleB: number): number;
/** Linearly interpolates between the angles passed in with wrapping
* @param {number} angleA
* @param {number} angleB
* @param {number} percent
* @return {number}
* @memberof Math */
export function lerpAngle(angleA: number, angleB: number, percent: number): number;
/** Linearly interpolates between values passed in using percent
* @param {number} valueA
* @param {number} valueB
* @param {number} percent
* @return {number}
* @memberof Math */
export function lerp(valueA: number, valueB: number, percent: number): number;
/** Applies smoothstep function to the percentage value
* @param {number} percent
* @return {number}
* @memberof Math */
export function smoothStep(percent: number): number;
/** Returns the nearest power of two not less than the value
* @param {number} value
* @return {number}
* @memberof Math */
export function nearestPowerOfTwo(value: number): number;
/** Returns true if two axis aligned bounding boxes are overlapping
* this can be used for simple collision detection between objects
* @param {Vector2} posA - Center of box A
* @param {Vector2} sizeA - Size of box A
* @param {Vector2} posB - Center of box B
* @param {Vector2} [sizeB=vec2()] - Size of box B, uses a point if undefined
* @return {boolean} - True if overlapping
* @memberof Math */
export function isOverlapping(posA: Vector2, sizeA: Vector2, posB: Vector2, sizeB?: Vector2): boolean;
/** Returns true if a line segment is intersecting an axis aligned box
* @param {Vector2} start - Start of raycast
* @param {Vector2} end - End of raycast
* @param {Vector2} pos - Center of box
* @param {Vector2} size - Size of box
* @return {boolean} - True if intersecting
* @memberof Math */
export function isIntersecting(start: Vector2, end: Vector2, pos: Vector2, size: Vector2): boolean;
/** Returns an oscillating wave between 0 and amplitude with frequency of 1 Hz by default
* @param {number} [frequency] - Frequency of the wave in Hz
* @param {number} [amplitude] - Amplitude (max height) of the wave
* @param {number} [t=time] - Value to use for time of the wave
* @param {number} [offset] - Value to use for time offset of the wave
* @return {number} - Value waving between 0 and amplitude
* @memberof Math */
export function wave(frequency?: number, amplitude?: number, t?: number, offset?: number): number;
/** Formats seconds to mm:ss style for display purposes
* @param {number} t - time in seconds
* @return {string}
* @memberof Utilities */
export function formatTime(t: number): string;
/** Fetches a JSON file from a URL and returns the parsed JSON object. Must be used with await!
* @param {string} url - URL of JSON file
* @return {Promise<object>}
* @memberof Utilities */
export function fetchJSON(url: string): Promise<object>;
/** Save a text file to disk
* @param {string} text
* @param {string} [filename]
* @param {string} [type]
* @memberof Utilities */
export function saveText(text: string, filename?: string, type?: string): void;
/** Save a canvas to disk
* @param {HTMLCanvasElement|OffscreenCanvas} canvas
* @param {string} [filename]
* @param {string} [type]
* @memberof Utilities */
export function saveCanvas(canvas: HTMLCanvasElement | OffscreenCanvas, filename?: string, type?: string): void;
/** Save a data url to disk
* @param {string} url
* @param {string} [filename]
* @param {number} [revokeTime] - how long before revoking the url
* @memberof Utilities */
export function saveDataURL(url: string, filename?: string, revokeTime?: number): void;
/** Share content using the native share dialog if available
* @param {string} title - title of the share
* @param {string} url - url to share
* @param {Function} [callback] - Called when share is complete
* @memberof Utilities */
export function shareURL(title: string, url: string, callback?: Function): void;
/** Read save data from local storage
* @param {string} saveName - unique name for the game/save
* @param {Object} [defaultSaveData] - default values for save
* @return {Object}
* @memberof Utilities */
export function readSaveData(saveName: string, defaultSaveData?: any): any;
/** Write save data to local storage
* @param {string} saveName - unique name for the game/save
* @param {Object} saveData - object containing data to be saved
* @memberof Utilities */
export function writeSaveData(saveName: string, saveData: any): void;
/** Random global functions
* @namespace Random */
/** Returns a random value between the two values passed in
* @param {number} [valueA]
* @param {number} [valueB]
* @return {number}
* @memberof Random */
export function rand(valueA?: number, valueB?: number): number;
/** Returns a floored random value between the two values passed in
* The upper bound is exclusive. (If 2 is passed in, result will be 0 or 1)
* @param {number} valueA
* @param {number} [valueB]
* @return {number}
* @memberof Random */
export function randInt(valueA: number, valueB?: number): number;
/** Randomly returns true or false given the chance of true passed in
* @param {number} [chance]
* @return {boolean}
* @memberof Random */
export function randBool(chance?: number): boolean;
/** Randomly returns either -1 or 1
* @return {number}
* @memberof Random */
export function randSign(): number;
/** Returns a random Vector2 within a circular shape
* @param {number} [radius]
* @param {number} [minRadius]
* @return {Vector2}
* @memberof Random */
export function randInCircle(radius?: number, minRadius?: number): Vector2;
/** Returns a random Vector2 with the passed in length
* @param {number} [length]
* @return {Vector2}
* @memberof Random */
export function randVec2(length?: number): Vector2;
/** Returns a random color between the two passed in colors, combine components if linear
* @param {Color} [colorA=WHITE]
* @param {Color} [colorB=BLACK]
* @param {boolean} [linear]
* @return {Color}
* @memberof Random */
export function randColor(colorA?: Color, colorB?: Color, linear?: boolean): Color;
/**
* Seeded random number generator
* - Can be used to create a deterministic random number sequence
* @memberof Engine
* @example
* let r = new RandomGenerator(123); // random number generator with seed 123
* let a = r.float(); // random value between 0 and 1
* let b = r.int(10); // random integer between 0 and 9
* r.seed = 123; // reset the seed
* let c = r.float(); // the same value as a
*/
export class RandomGenerator {
/** Create a random number generator with the seed passed in
* @param {number} [seed] - Starting seed or engine default seed */
constructor(seed?: number);
/** @property {number} - random seed */
seed: number;
/** Returns a seeded random value between the two values passed in
* @param {number} [valueA]
* @param {number} [valueB]
* @return {number} */
float(valueA?: number, valueB?: number): number;
/** Returns a floored seeded random value the two values passed in
* @param {number} valueA
* @param {number} [valueB]
* @return {number} */
int(valueA: number, valueB?: number): number;
/** Randomly returns true or false given the chance of true passed in
* @param {number} [chance]
* @return {boolean} */
bool(chance?: number): boolean;
/** Randomly returns either -1 or 1 deterministically
* @return {number} */
sign(): number;
/** Returns a seeded random value between the two values passed in with a random sign
* @param {number} [valueA]
* @param {number} [valueB]
* @return {number} */
floatSign(valueA?: number, valueB?: number): number;
/** Returns a random angle between -PI and PI
* @return {number} */
angle(): number;
/** Returns a seeded vec2 with size between the two values passed in
* @param {number} valueA
* @param {number} [valueB]
* @return {Vector2} */
vec2(valueA?: number, valueB?: number): Vector2;
/** Returns a random color between the two passed in colors, combine components if linear
* @param {Color} [colorA=WHITE]
* @param {Color} [colorB=BLACK]
* @param {boolean} [linear]
* @return {Color} */
randColor(colorA?: Color, colorB?: Color, linear?: boolean): Color;
/** Returns a new color that has each component randomly adjusted
* @param {Color} color
* @param {number} [amount]
* @param {number} [alphaAmount]
* @return {Color} */
mutateColor(color: Color, amount?: number, alphaAmount?: number): Color;
}
/**
* 2D Vector object with vector math library
* - Functions do not change this so they can be chained together
* @memberof Engine
* @example
* let a = new Vector2(2, 3); // vector with coordinates (2, 3)
* let b = new Vector2; // vector with coordinates (0, 0)
* let c = vec2(4, 2); // use the vec2 function to make a Vector2
* let d = a.add(b).scale(5); // operators can be chained
*/
export class Vector2 {
/** Create a 2D vector with the x and y passed in, can also be created with vec2()
* @param {number} [x] - X axis location
* @param {number} [y] - Y axis location */
constructor(x?: number, y?: number);
/** @property {number} - X axis location */
x: number;
/** @property {number} - Y axis location */
y: number;
/** Sets values of this vector and returns self
* @param {number} [x] - X axis location
* @param {number} [y] - Y axis location
* @return {Vector2} */
set(x?: number, y?: number): Vector2;
/** Sets this vector from another vector and returns self
* @param {Vector2} v - other vector
* @return {Vector2} */
setFrom(v: Vector2): Vector2;
/** Returns a new vector that is a copy of this
* @return {Vector2} */
copy(): Vector2;
/** Returns a copy of this vector plus the vector passed in
* @param {Vector2} v - other vector
* @return {Vector2} */
add(v: Vector2): Vector2;
/** Returns a copy of this vector minus the vector passed in
* @param {Vector2} v - other vector
* @return {Vector2} */
subtract(v: Vector2): Vector2;
/** Returns a copy of this vector times the vector passed in
* @param {Vector2} v - other vector
* @return {Vector2} */
multiply(v: Vector2): Vector2;
/** Returns a copy of this vector divided by the vector passed in
* @param {Vector2} v - other vector
* @return {Vector2} */
divide(v: Vector2): Vector2;
/** Returns a copy of this vector scaled by the vector passed in
* @param {number} s - scale
* @return {Vector2} */
scale(s: number): Vector2;
/** Returns the length of this vector
* @return {number} */
length(): number;
/** Returns the length of this vector squared
* @return {number} */
lengthSquared(): number;
/** Returns the distance from this vector to vector passed in
* @param {Vector2} v - other vector
* @return {number} */
distance(v: Vector2): number;
/** Returns the distance squared from this vector to vector passed in
* @param {Vector2} v - other vector
* @return {number} */
distanceSquared(v: Vector2): number;
/** Returns a new vector in same direction as this one with the length passed in
* @param {number} [length]
* @return {Vector2} */
normalize(length?: number): Vector2;
/** Returns a new vector clamped to length passed in
* @param {number} [length]
* @return {Vector2} */
clampLength(length?: number): Vector2;
/** Returns the dot product of this and the vector passed in
* @param {Vector2} v - other vector
* @return {number} */
dot(v: Vector2): number;
/** Returns the cross product of this and the vector passed in
* @param {Vector2} v - other vector
* @return {number} */
cross(v: Vector2): number;
/** Returns a copy this vector reflected by the surface normal
* @param {Vector2} normal - surface normal (should be normalized)
* @param {number} restitution - how much to bounce, 1 is perfect bounce, 0 is no bounce
* @return {Vector2} */
reflect(normal: Vector2, restitution?: number): Vector2;
/** Returns the clockwise angle of this vector, up is angle 0
* @return {number} */
angle(): number;
/** Sets this vector with clockwise angle and length passed in
* @param {number} [angle]
* @param {number} [length]
* @return {Vector2} */
setAngle(angle?: number, length?: number): Vector2;
/** Returns copy of this vector rotated by the clockwise angle passed in
* @param {number} angle
* @return {Vector2} */
rotate(angle: number): Vector2;
/** Sets this this vector to point in the specified integer direction (0-3), corresponding to multiples of 90 degree rotation
* @param {number} [direction]
* @param {number} [length]
* @return {Vector2} */
setDirection(direction?: number, length?: number): Vector2;