Core Functions
Core Methods
- asyncInit
- cls
- defineColors
- doFrame
- downloadScreenshot
- drawImage
- drawRect
- endAsyncImpl
- failAsync
- fillRect
- getBeepContainerEl
- getColorHex
- getHighResDataURL
- getNow
- handleCrash
- hasPendingAsync
- init
- initialized
- isAndroid
- isIOS
- isMobile
- isTouchDevice
- nextCursorLocation
- preflight
- resolveAsync
- restoreScreen
- saveScreen
- setColor
- setCursorLocation
- setFrameHandler
- startAsync
- updateLayout
- updateLayout2d
beep8.Core.asyncInit(callback) async
Asynchronously initializes the engine.
This function sets up the canvas, initializes subsystems, and then calls the callback function if it’s set.
Parameters
- callback (Function): The function to call when the engine is initialized.
beep8.Core.cls([bgColor])
Clears the screen and resets the cursor to the top-left corner.
It will optionally also set the background colour. By default it uses the specified background but you can override this yourself.
Parameters
- [bgColor] (number): Optional background color index.
beep8.Core.defineColors(colors)
Sets the colors used for text and background.
Parameters
- colors (array): A list of colours.
beep8.Core.doFrame() async
Run the game loop.
This function ensures we stay as close to the target frame rate as possible.
beep8.Core.downloadScreenshot()
Download the current screen as a PNG image.
beep8.Core.drawImage(img, x, y [,srcX] [,srcY] [,width] [,height])
Draws an image.
This function is a wrapper around the canvas drawImage() function and will draw the image at any x,y position. It does not use the cursor position.
Parameters
- img (HTMLImageElement): The image to draw.
- x (number): The x-coordinate of the upper-left corner of the image.
- y (number): The y-coordinate of the upper-left corner of the image.
- [srcX] (number): The x-coordinate of the upper-left corner of the source image.
- [srcY] (number): The y-coordinate of the upper-left corner of the source image.
- [width] (number): The width of the image.
- [height] (number): The height of the image.
beep8.Core.drawRect(x, y, width, height)
Draws a rectangle of the specified width and height.
This ignores the cursor position.
Parameters
- x (number): The x-coordinate of the upper-left corner of the rectangle.
- y (number): The y-coordinate of the upper-left corner of the rectangle.
- width (number): The width of the rectangle.
- height (number): The height of the rectangle.
beep8.Core.endAsyncImpl(asyncMethodName, isError, result)
Ends an asynchronous operation.
Parameters
- asyncMethodName (string): The name of the asynchronous method.
- isError (boolean): Whether the operation failed.
- result (any): The result of the operation.
beep8.Core.failAsync(asyncMethodName, error)
Fails an asynchronous operation.
Parameters
- asyncMethodName (string): The name of the asynchronous method.
- error (any): The error that occurred.
beep8.Core.fillRect(x, y, width, height)
Draws a filled rectangle using the current colours.
Ignores the cursor position.
Parameters
- x (number): The x-coordinate of the upper-left corner of the rectangle.
- y (number): The y-coordinate of the upper-left corner of the rectangle.
- width (number): The width of the rectangle.
- height (number): The height of the rectangle.
beep8.Core.getBeepContainerEl()
Gets the container element for the engine.
This is the element under which the rendering canvas is created. If the container is not specified in the configuration, this will be the body element.
Returns
- (HTMLElement): The container element.
beep8.Core.getColorHex(c)
Gets the color for the specified index.
Parameters
- c (number): The color index.
Returns
- (string): The color.
beep8.Core.getHighResDataURL(canvas [,scale] [,mimeType] [,quality])
Get a high-resolution data URL for the specified canvas.
Parameters
- canvas (HTMLCanvasElement): The canvas to get the data URL for.
- [scale] (number): The scale factor. (default: 4)
- [mimeType] (string): The MIME type. (default: “image/png”)
- [quality] (number): The quality. (default: 1)
Returns
- (string): The data URL.
beep8.Core.getNow()
Gets the current time in milliseconds.
This is used for rendering and animation, and can also be used in the game to get the current time for things like timers.
You can get the game start time by calling beep8.Core.startTime.
Returns
- (number): The current time in milliseconds.
beep8.Core.handleCrash([errorMessage])
Handles a crash.
Parameters
- [errorMessage] (string): error”] - The error message to display. (default: “Fatal)
beep8.Core.hasPendingAsync(asyncMethodName)
Checks if there is a pending asynchronous operation.
Parameters
- asyncMethodName (string): The name of the asynchronous method.
Returns
- (boolean): True if there is a pending asynchronous operation.
beep8.Core.init(callback)
Initializes the engine.
This merges config properties and then calls beep8.Core.asyncInit() to prepare assets.
Parameters
- callback (Function): The function to call when the engine is initialized.
beep8.Core.initialized()
Checks if the engine has been initialized.
Returns
- (boolean): True if the engine has been initialized.
beep8.Core.isAndroid()
Is this an Android device?
Returns
- (boolean): True if this is an Android device.
beep8.Core.isIOS()
Is this an iOS device?
Returns
- (boolean): True if this is an iOS device.
beep8.Core.isMobile()
Is this a mobile device?
Returns
- (boolean): True if this is a mobile device.
beep8.Core.isTouchDevice()
Is this a touch device?
Returns
- (boolean): True if this is a touch device.
beep8.Core.nextCursorLocation()
Move the cursor to the next character.
This adjusts the drawing position without actually drawing anything.
beep8.Core.preflight(apiMethod)
Checks if the engine (and specified api method) is ready to run.
This function checks if the engine has crashed, if the initAsync() method has been called, and if there is a pending asynchronous operation.
Parameters
- apiMethod (string): The name of the API method being called.
beep8.Core.resolveAsync(asyncMethodName, result)
Resolves an asynchronous operation.
This function should be called at the end of an asynchronous method.
Parameters
- asyncMethodName (string): The name of the asynchronous method.
- result (any): The result of the operation.
beep8.Core.restoreScreen(screenData)
Restores the screen.
Parameters
- screenData (ImageData): The screen to restore.
beep8.Core.saveScreen()
Generates the bitmap data for the current screen and returns it to you.
Returns
- (ImageData): The saved screen.
beep8.Core.setColor(fg [,bg])
Sets the colors used for text and background.
Parameters
- fg (number): The foreground color.
- [bg] (number): The background color. (default: undefined)
beep8.Core.setCursorLocation(col, row)
Sets the cursor location.
The cursor location is used for text rendering and is the position where the next character will be drawn.
Characters can be text or images, drawn using the loaded fonts.
Parameters
- col (number): The column.
- row (number): The row.
beep8.Core.setFrameHandler(callback [,targetFps])
Set the callback function for the game loop. Will be called targetFps times per second.
Parameters
- callback (Function): The function to call.
- [targetFps] (number): The target frames per second. (default: 30)
beep8.Core.startAsync(asyncMethodName, resolve, reject)
Starts an asynchronous operation.
This function should be called at the beginning of an asynchronous method. It sets up the pendingAsync object, which is used to track the state of the asynchronous operation.
This function should be called at the beginning of an asynchronous method.
Parameters
- asyncMethodName (string): The name of the asynchronous method.
- resolve (Function): The function to call when the operation is successful.
- reject (Function): The function to call when the operation fails.
beep8.Core.updateLayout(renderNow)
Updates the layout.
Parameters
- renderNow (boolean): Whether to render immediately.
beep8.Core.updateLayout2d()
Updates the layout of the 2D canvas.