# Faux Manual

This document is up-to-date as of May 13, 2023.

Faux is a [fantasy console](https://en.wikipedia.org/wiki/Fantasy_video_game_console) heavily inspired by [PICO-8](https://www.lexaloffle.com/pico-8.php), but with several alternative design choices. It is probably nowhere near as resource efficient either.

This console being in its infancy, this document is literally the only documentation that exists. As such, anything not found in this documentation should be asked of the author, or assumed to be similar to PICO-8.

## What's different from PICO-8?

Glad you asked.

Probably the most important difference is that cartridges are written in JavaScript rather than Lua.

Another huge design difference, is that a Faux cartridge is made up of up to 16 "sheets". Each sheet can store a certain amount of data in a specific format. Sheets can be used to hold sprite data, map data, code, and eventually music/sfx, fonts, and other types of data.

## Code

The code used in faux cartridges is JavaScript, but without a lot of the language built-ins. Instead, faux provides it's own api to accomplish things like drawing sprites, etc.

In the code editor, a few special characters can be inserted by holding alt while pressing another key. Currently, the characters that can be added in this way are:

Symbols for arrows:

- `⬆️`
- `⬅️`
- `⬇️`
- `➡️`

And math symbols:

- `π`

### Graphics

- `cls(color?: number)` clears the screen to the given color if provided, otherwise, black.
- `camera(x: number, y: number)` draws everything from here on with an offset of (-x, -y). 
- `sprsht(sheet: number)` sets the current spritesheet used for drawing sprites with the `spr` function below.
- `spr(x: number, y: number, sprite: number)` draws the given sprite from the current spritesheet at (x,y).
- `txt(x: number, y: number, text: string)` draws the given text at (x,y).
- `rectfill(x: number, y: number, w: number, h: number, color: number)` fills a rectangle with the given color with a top-left corner at (x,y) and a width of w and a height of h.
- `rect(x: number, y: number, w: number, h: number, color: number)` outlines a rectangle with the given color with a top-left corner at (x,y) and a width of w and a height of h.
- `circfill(x: number, y: number, r: number, color: number)` fills a circle with the given color with a center at (x,y) and a radius of r.
- `circ(x: number, y: number, r: number, color: number)` outlines a circle with the given color with a center at (x,y) and a radius of r.
- `ovalfill(x0: number, y0: number, x1: number, y1: number, color: number)` fills an ellipse with the given color whose bounding box has a top-left corner at (x0,y0) and a bottom-right corner at (x1,y1).
- `oval(x0: number, y0: number, x1: number, y1: number, color: number)` outlines an ellipse with the given color whose bounding box has a top-left corner at (x0,y0) and a bottom-right corner at (x1,y1).
- `pset(x: number, y: number, color: number)` sets the color of the pixel at (x,y) to the given color.
- `map(mapSheet: number, tileX: number, tileY: number, screenX: number, screenY: number, tileW: number, tileH: number)` draws the map of the given sheet to the screen at (screenX,screenY) beginning from from the tile at (tileX,tileY) and drawing tileW many tiles across, and tileH many tiles down.

### Map

- `mgetsht(mapSheet: number, x: number, y: number)` returns the sheet number of the sprite at tile (x,y) in the given map
- `mgetspr(mapSheet: number, x: number, y: number)` returns the sprite number within it's sheet of the sprite at tile (x,y) in the given map
- `mset(mapSheet: number, x: number, y: number, sprSheet: number, spr: number)` sets the sprite at tile (x,y) in the given map to the given sprite of the given spritesheet.

### Input

- `btn(key: string | number)` returns a boolean indicating whether the given key is currently held down. 
- `btnp(key: string | number)` returns a boolean indicating whether the given key has just been pressed. Fires repeatedly after a time, as when typing.
- `btnr(key: string | number)` returns a boolean indicating whether the given key has just been released.

There are also values:

- `⬆️` a number that corresponds to the up arrow.
- `⬅️` a number that corresponds to the left arrow.
- `⬇️` a number that corresponds to the down arrow.
- `➡️` a number that corresponds to the right arrow.

### System

- `save(name: string)` saves the cartridge
- `load(name: string)` loads the cartridge
- `play()` plays the cartridge

### Misc.

- `code(sheet: number)` executes the code in the given sheet as a function and returns any return value.
- `log(...args: any)` logs the given args to the stdout of faux.

### REPL Only

- `print(val: any)` only really should be used in the repl.
- `printVal(val: any)` only really should be used in the repl.

### Math functions

These are all identical to what Javascript typically has under the `Math` namespace:

- `max`
- `min`
- `floor`
- `ceil`
- `sin`
- `cos`
- `atan2`
- `sqrt`
- `abs`
- `rand`

Faux also provides:

- `π` which is just `Math.PI` in regular JS.

### JS Objects

The following JS objects/functions/value are exactly provided as is in a typical JS environment:

- [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
- [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
- [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
- [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
- [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
- [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
- [`Infinity`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity)
- [`JSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)
- [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
- [`NaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN)
- [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)
- [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
- [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
- [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
- [`Reflect`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect)
- [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp)
- [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)
- [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)
- [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol)
- [`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)
- [`WeakRef`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef)
- [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet)
- [`isFinite`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isFinite)
- [`isNaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isNaN)
- [`eval`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval)