Public API
Public Methods
- addScene
- cls
- col
- color
- convChar
- cursor
- drawActor
- drawImage
- drawImageRect
- drawRect
- drawText
- fillRect
- frame
- getBgColor
- getContext
- getFgColor
- getFont
- getFontByName
- getScene
- init
- key
- keyp
- locate
- measure
- playSfx
- playSong
- playSound
- printBox
- printCentered
- printChar
- printRect
- redefineColors
- render
- restoreScreen
- row
- saveScreen
- setFont
- setTileFont
- spr
- sprActor
- stopSound
- switchScene
- wrapText
beep8.addScene(name, update)
Add a new game scene.
Parameters
- name (string): The name of the scene.
- update (Function): The update function for the scene.
beep8.cls([bgColor])
Clears the screen using the specified or current background color.
Parameters
- [bgColor] (number): Optional background color index. (default: undefined)
beep8.col()
Returns the cursor’s current column.
Returns
- (number): The cursor’s current column.
beep8.color(fg [,bg])
Sets the foreground and/or background color.
If you set the background color to -1, it will be transparent.
Parameters
- fg (number): The foreground color.
- [bg] (number): The background color (optional). (default: undefined)
beep8.convChar(charCode)
Converts a character code to its integer representation if needed.
Parameters
-
charCode (*number string*): The character code to convert.
Returns
- (number): The integer representation of the character code.
beep8.cursor(visible)
Shows or hides the cursor.
Parameters
- visible (boolean): If true, show the cursor. If false, hide the
beep8.drawActor(ch, frame [,direction])
Draws an actor on the screen with a specific frame and direction.
Parameters
- ch (number): The character code of the actor.
- frame (number): The frame to draw.
- [direction] (number): The direction to draw the actor in. 0 = right, 1 = left. (default: 0)
beep8.drawImage(x, y, image)
Draws an image (previously loaded with beep8.loadImage).
Parameters
- x (number): The X coordinate of the top-left of the image.
- y (number): The Y coordinate of the top-left of the image.
- image (HTMLImageElement): The image to draw.
beep8.drawImageRect(x, y, image, srcX, srcY, width, height)
Draws a rectangular part of an image (previously loaded with beep8.loadImage).
Parameters
- x (number): The X coordinate of the top-left of the image.
- y (number): The Y coordinate of the top-left of the image.
- image (HTMLImageElement): The image to draw.
- srcX (number): The X coordinate of the top-left of the rectangle
- srcY (number): The Y coordinate of the top-left of the rectangle
- width (number): The width in pixels of the rectangle to be drawn.
- height (number): The height in pixels of the rectangle to be
beep8.drawRect(x, y, width, height)
Draws a rectangle (border only) using the current foreground color.
Parameters
- x (number): The X coordinate of the top-left corner.
- y (number): The Y coordinate of the top-left corner.
- width (number): The width of the rectangle in pixels.
- height (number): The height of the rectangle in pixels.
beep8.drawText(x, y, text [,fontId])
Draws text at an arbitrary pixel position on the screen, not following the “row and column” system.
Parameters
- x (number): The X coordinate of the top-left of the text.
- y (number): The Y coordinate of the top-left of the text.
- text (string): The text to print.
- [fontId] (string): The font ID to use. (default: null)
beep8.fillRect(x, y, width, height)
Draws a filled rectangle using the current foreground color.
Parameters
- x (number): The X coordinate of the top-left corner.
- y (number): The Y coordinate of the top-left corner.
- width (number): The width of the rectangle in pixels.
- height (number): The height of the rectangle in pixels.
beep8.frame(handler [,fps])
Sets the frame handler, that is, the function that will be called on every frame to render the screen. This is only needed if you are making a real time game. For asynchronous games, you can update the screen manually.
Parameters
- handler (Function): The frame handler function.
- [fps] (number): The target frames per second. Recommended: 30. (default: 30)
beep8.getBgColor()
Gets the current background color. -1 means transparent.
Returns
- (number): The current background color.
beep8.getContext()
Returns the raw canvas 2D context for drawing.
Returns
- (CanvasRenderingContext2D): The raw HTML 2D canvas context.
beep8.getFgColor()
Gets the current foreground color.
Returns
- (number): The current foreground color.
beep8.getFont()
Returns the current font.
Returns
- (string): The current font.
beep8.getFontByName(fontName)
Returns the font object for the given font name.
Parameters
- fontName (string): The name of the font.
Returns
- (Object): The font object.
beep8.getScene()
Gets the current active scene.
Returns
-
(*Object null*): The active scene object, or null if no scene is active.
beep8.init(callback [,options])
Initializes the API. This must be called before other functions and must finish executing before other API functions are called. Once the supplied callback is called, you can start using beep8 functions.
Parameters
- callback (Function): The callback to call when initialization is done.
- [options] (Object): Optional options object.
beep8.key(keyName)
Checks if the given key is currently pressed or not.
Parameters
- keyName (string): The name of the key.
Returns
- (boolean): True if the key is pressed, otherwise false.
beep8.keyp(keyName)
Checks if the given key was JUST pressed on this frame.
Parameters
- keyName (string): The name of the key.
Returns
- (boolean): True if the key was just pressed, otherwise false.
beep8.locate(col [,row])
Places the cursor at the given screen column and row. All drawing and printing operations will start from here.
Parameters
- col (number): The column where the cursor is to be placed.
- [row] (number): The row where the cursor is to be placed (optional).
beep8.measure(text)
Measures the size of the given text without printing it.
Parameters
- text (string): The text to measure.
Returns
- (Object): An object with {cols, rows} indicating the dimensions.
beep8.playSfx(sfx)
Play a sound effect.
Parameters
- sfx (string): The name of the sound effect to play.
beep8.playSong(song)
Play a song.
Parameters
- song (string): The name of the song to play.
beep8.playSound(sfx [,volume] [,loop])
Plays a sound (previously loaded with beep8.loadSound).
Parameters
- sfx (HTMLAudioElement): The sound to play.
- [volume] (number): The volume to play the sound at. (default: 1)
- [loop] (boolean): If true, play the sound in a loop. (default: false)
beep8.print(text [,wrapWidth])
Prints text at the cursor position, using the current foreground and background colors.
The text can contain embedded newlines and they will behave as expected: printing will continue at the next line.
If PRINT_ESCAPE_START and PRINT_ESCAPE_END are defined in CONFIG, then you can also use escape sequences. For example:
- sets the color to 1
- sets the background to 2 (red)
- changes the current font to ‘fontname’ (temporary)
- resets the color and font to their states before printing started
Note: Font changes using escape sequences are temporary and will be reset after the print operation is complete.
See example-printing.html for an example.
Parameters
- text (string): The text to print.
- [wrapWidth] (number): The width to wrap text at. -1 for no wrapping. (default: -1)
beep8.printBox(widthCols, heightRows [,fill] [,borderChar])
Prints a box with a border of the given size starting at the cursor position, using border-drawing characters.
Parameters
- widthCols (number): Width of the box in screen columns, including
- heightRows (number): Height of the box in screen rows, including
- [fill] (boolean): If true, fill the interior with spaces. (default: true)
- [borderChar] (number): The first border-drawing character to (default: 54)
beep8.printCentered(text, width)
Prints text centered horizontally in a field of the given width.
If the text is bigger than the width, it will overflow it.
Parameters
- text (string): The text to print.
- width (number): The width of the field, in characters.
beep8.printChar(charCode [,numTimes])
Prints a character at the current cursor position, advancing the cursor position.
Parameters
-
charCode (*number string*): The character to print, as an integer - [numTimes] (number): How many times to print the character. (default: 1)
beep8.printRect(widthCols, heightRows [,charCode])
Prints a rectangle of the given size with the given character, starting at the current cursor position.
Parameters
- widthCols (number): Width of the rectangle in screen columns.
- heightRows (number): Height of the rectangle in screen rows.
-
[charCode] (*number string*): The character to print. (default: 8)
beep8.redefineColors(colors)
Redefines the colors, assigning new RGB values to each color.
Parameters
-
colors (*Array
*): An array of RGB values.
beep8.render()
Forces the screen to render right now. Useful for immediate redraw in animations.
You only need this if you are doing some kind of animation on your own and you want to redraw the screen immediately to show the current state.
Otherwise the screen repaints automatically when waiting for user input.
beep8.restoreScreen(screenData)
Restores the contents of the screen using an ImageData object.
Parameters
- screenData (ImageData): The ImageData object with the screen’s
beep8.row()
Returns the cursor’s current row.
Returns
- (number): The cursor’s current row.
beep8.saveScreen()
Saves the contents of the screen into an ImageData object and returns it.
Returns
- (ImageData): An ImageData object with the screen’s contents.
beep8.setFont([fontId])
Sets the current font for text-based operations.
Parameters
- [fontId] (string): The font ID to set. Pass null or (default: “default”)
beep8.setTileFont([fontId])
Sets the current tile font for text-based operations.
Parameters
- [fontId] (string): The font ID to set. Pass null or (default: “tiles”)
beep8.spr(ch, x, y)
Draws a sprite on the screen.
Parameters
-
ch (*number string*): The character code of the sprite. - x (number): The X position at which to draw.
- y (number): The Y position at which to draw.
beep8.sprActor(ch, x, y)
Draws a sprite on the screen.
Parameters
-
ch (*number string*): The character code of the sprite. - x (number): The X position at which to draw.
- y (number): The Y position at which to draw.
Returns
- (boolean): True if the sprite was drawn, otherwise false.
beep8.stopSound(sfx)
Stops a sound (previously loaded with beep8.playSound).
Parameters
- sfx (HTMLAudioElement): The sound to stop playing.
beep8.switchScene(name)
Switches to a specified scene by name.
Parameters
- name (string): The name of the scene to switch to.
beep8.wrapText(text, width)
Returns the text with line breaks inserted so that it fits within the given width.
Parameters
- text (string): The text to wrap.
- width (number): The width to wrap text at.
Returns
- (string): The wrapped text.