recursal/Fanatic-Fandom huggingface dataset:
DrawState

PICO-8 maintains a set of variables that affect how the drawing functions work. For example, it remembers the current "pen color," and when you call functions such as circ() or print() without the optional color parameter, it uses the current pen color. The pen color is changed whenever you provide a color parameter to a draw function, and you can change it directly by calling the color() function.

A typical use of the draw state is to use the same feature for a series of related consecutive draw calls. For example, to draw a the cockpit of a spaceship, the game can call clip() to set the clipping region for the window, call draw functions for the objects outside the window, then call clip() again to set the clipping region for the cockpit controls, and so on.

The following features are stored in the draw state and affect how graphics features work:

 Camera position

The draw state is stored in the addressable memory region 0x5f00-0x5f3f. This is useful if you want to save and restore the current draw state by copying the memory region with memcpy().
Cd

cd [path]
Changes the current working directory.
path

The path to the new working directory.

PICO-8 cartridge storage uses a hierarchical filesystem of directories that corresponds to that of the host operating system. Similar to other command shells, PICO-8 has a notion of a *current working directory*, a location in this hierarchy where other commands that operate on files, like `save` or `ls`, perform an action.

When given an argument, the `cd` command changes the current working directory. The argument is a *path* to the new directory, either a *relative path* from the current working directory or an *absolute path* from the root of the cartridge storage area. An absolute path begins with a forward slash (`/`) character. A relative path does not.

Paths use the forward slash (`/`) to separate directory names. This is true even if the host operating system uses a different path delimiter.

A relative path can use two dots (`..`) to indicate traversing to the parent directory.

When run without arguments, `cd` prints the current working directory's absolute path, and does not change it.

## Examples

Consider a cartridge storage area with the following directories and files:

```
/
  demos/
    api.p8
    jelpi.p8
  projects/
    helloworld/
      hello.p8
      hello2.p8
    squashy/
      squashy.p8

```

From the PICO-8 command prompt:

```
> cd demos

```

The current working directory is now `/demos/`.

```
> cd ..

```

The current working directory is now `/`.

```
> cd projects/squashy

```

The current working directory is now `/projects/squashy/`.

```
> cd ../helloworld

```

The current working directory is now `/projects/helloworld/`.

```
> cd /

```

The current working directory is now `/`.

To print the current working directory:

```
> cd

```

## See also

* `ls`
* `folder`
* `mkdir`
Lander on Planet Cheese

Creator
 Genre
 Player Count

## Description

You are stuck on planet cheese. You could slice your way out if only you had a slicer. Luckily you have a slicer detector...

## Rules

* The game starts with the player's lander sitting on a surface. They must guide the lander throughout the planet in order to find their slicer.
* The slicer detector points in the direction of the player's cheese slicer. Moving the lander in the direction of the slicer will bring the player closer to it.
* Fuel is constantly being used once the lander is airborne; however, the player can land softly on any flat surface in order to refuel.
* Colliding with any surface, running out of fuel, landing on a surface too hard or not landing directly on most surfaces (i. e. if a landing pad is not on a surface) will end the game.
* The player wins the game by finding and making contact with the slicer.

## Controls

* At the title screen, press z or x to start a new game.
* Use the x key to use the slicer detector.
* Use the z key to thrust.
* Use the arrow keys to turn your ship left and right.
* Use the p or Enter key to pause the game.
Bluestone's Awakening

Genre
 Player Count

## Description

The game features a blob creature named Bluestone who is dreaming about giving gifts to his friends. Once he delivers all of the gifts, he can wake up and go to work. However, there is an indigo creature which he must avoid.

## Controls

* Z: Jump (Hold button to jump higher)
* X: Grab/Release Object
* Left/Right: Movement
* Down: Duck/Hide
	+ If you're holding an item, enemies will just run past you and be unable to hurt you, but you can't move while ducking.

## Links

* BBS: https://www.lexaloffle.com/bbs/?pid=59762#p
* Itch.io: https://jclermont.itch.io/bluestones-awakening
Del

del( table, value )
Deletes the first occurrence of a value from a sequence in a table.
table

The table.

value

The value to match and remove.
The `del()` function searches a sequence in a table for an element that equals the given value then removes it. All subsequent values in the sequence shift down by one slot to keep the sequence contiguous.

Specifically, `del()` starts with the element at index 1, then increments the index while comparing elements to the given value. When it finds the first element that is equal to the value, it reassigns the indexes of the subsequent values until it reaches an unassigned index (`nil`).

The `del()` function returns the object being removed. This can be ignored, tested it to see if the removal was successful, or used as needed.

## Examples

Deleting elements using literal values:

```
t = {1, 3, 5, 3, 7, 5}
del(t, 3)  -- t = {1, 5, 3, 7, 5}
del(t, 7)  -- t = {1, 5, 3, 5}
del(t, 5)  -- t = {1, 3, 5}

del(t, 9)  -- not found, no changes to t

```

Deleting elements using their own value:

```
evens = {1, 2, 3, 4, 5, 6}
del(evens, evens[1])  -- evens = {2, 3, 4, 5, 6}
del(evens, evens[2])  -- evens = {2, 4, 5, 6}
del(evens, evens[3])  -- evens = {2, 4, 6}

```

In Lua, tables are compared by reference (memory location), not by contents. To delete a sub-table from a table, the right reference must be supplied:

```
-- create a table in 'f' so we can refer to it more than once
f = {"foo"}

-- create a table of tables
t = {}
add(t, {"bar"})
add(t, {"foo"}) -- this 1st "foo" table only \*looks\* like the one we created
add(t, {"baz"})
add(t, f)       -- this 2nd "foo" table \*is\* the one we created
add(t, {"bat"})

-- print the table
for v in all(t) do print(v[1]) end  -- bar foo baz foo bat

-- this fails to delete anything because the search parameter
-- only \*looks\* like the two "foo" tables in 't'
del(t, {"foo"})
for v in all(t) do print(v[1]) end  -- bar foo baz foo bat

-- this deletes the 2nd "foo" table because the search parameter 'f'
-- \*is\* the 2nd "foo" table
del(t, f)
for v in all(t) do print(v[1]) end  -- bar foo baz bat

-- this deletes the 1st "foo" table by using its reference,
-- taken directly from the parent table
del(t, t[2])
for v in all(t) do print(v[1]) end  -- bar baz bat

```

## See also

* Lua
* Tables
* `add()`
* `deli()`
* `all()`
* `foreach()`
* `pairs()`
* `ipairs()`
194-8

Creator
 Genre
 Player Count

## Description

Scrolling shooter where the player controls a plane that must shoot down targets while avoiding them and/or their fire for as long as possible.

## Rules

* Crafts move in certain patterns, initially traveling in either straight horizontal or vertical paths. After defeating several bosses, other vehicles will also zig-zag.
* Making contact with an enemy or one of its projectiles will cause the player to lose health (indicated by yellow hearts at the bottom right corner of the screen); once the player runs out of health the game will end.
* The player has two weapons: a primary main gun and a secondary Lazor. The main gun can have several shots onscreen at once but starts off weak; the Lazor is much stronger but needs to be strengthened via collecting power-ups in order to be used again.
* Enemies initially take several hits to be destroyed, although they often release power-ups. Once collected by the player, pink globes are used to build up the Lazor power (represented by a bar at the bottom left of the screen), whereas the less common yellow orbs will strengthen the player’s main gun, along with increasing the size of its projectiles. It can also replenish the player’s health.
* After the player reaches certain point thresholds they will find themselves in a boss battle, which fires many shots at once and takes many hits to be destroyed. If the player is able to defeat it then they will continue the game at a higher difficulty level, as ground targets that fire appear on level 2 (which none of the enemy aircraft fires at the player during the first level), one type of airborne target fires and another moves in a zig-zagging pattern appears on level 3, etc.

## Controls

* At the title screen, press the x key to play game.
* Use the arrow keys to move.
* Use the x key to fire main guns.
* Use the z key to shoot the Lazor (when available).
* Press the Enter or p key to pause the game.
BuzzKill

Creator
 Genre
 Player Count

## Description

The player must clear out 10 levels’ worth of “bees, hives and honeycombs to advance [through] 10 levels” of gameplay while avoiding various dangers.

## Rules

* Honeycombs appear overhead at the beginning of every level, which start releasing killer bees after a few seconds. They can only be removed once the player first freezes them with smoke from their blaster, then shoots them, although two power-ups, when caught, will also enable the player to remove them as well. When not destroyed quickly enough they can multiply.
* Regular bees can be shot with fireballs and can be hindered by smoke. Large bees (not as common) take many more hits to kill and they fire large shots at the player and at a larger volume than with regular bees and they, nor their shots are hindered by smoke. The bee boss (which doesn’t appear until late in the game) takes many hits until it is destroyed, it fires the same kind of shots as large bees and it can produce honeycombs.
* Nests start appearing after several levels and take many shots to bring down and they produce large bees.
* Whenever the player uses a weapon, it takes up some of their power (represented by a bar at the bottom of the screen). The more power the player uses up, the more their ability to fire their weapons decreases, although the power bar will increase when the player doesn’t fire and when a certain power-up is collected.
* Getting hit by a bee’s fire or a falling nest will cause the loss of a blaster and the game will end when there are no more blasters in reserve. An extra blaster is awarded at 200 bee kills, however.
* There are several power-ups that appear during the game, being of Unlimited power, which the player’s firepower (fireballs and smoke usage) will not decrease for several seconds. The Freeze all honeycombs powerup freezes all onscreen honeycombs for several seconds, allowing them to be destroyed by fireballs, and a Honeycomb bomb causes one of the onscreen honeycombs to flash for several seconds, which shooting it will destroy it and several other surrounding honeycombs.
* If all 10 levels of the game are beaten, an endless mode will be unlocked. Rather than following the screen order of the regular/Challenge mode of the game, the levels are randomized and there is no boss or end level, along with a separate high score for the mode.

## Controls

* At the title screen, press the x key to turn off music.
* At the title screen, highlight the area to view several other options (read instructions, select Challenge or Endless mode [if applicable]) by the arrow keys and choose an option by pressing the z key.
* At the title screen, press the z key once highlighted on the game of choice in order to play.
* Use the left/right arrow keys to move the blaster.
* Press the z key to shoot fireballs.
* Press the x key to blow smoke.
* Press the Enter or p key to pause the game.
Math

PICO-8 can do mathematical operations on numbers, including arithmetic and trigonometric functions. All operations use PICO-8's number value type, a 16-bit fixed point type with a range of -32768.0 to 32767.9999847412109375 (0x8000.0000 to 0x7fff.ffff).

To assist with common game graphics tasks, PICO-8's trigonometric functions use an input range of 0.0 to 1.0, which is equivalent to a range of 0 to 2 PI radians, or 0 to 360 degrees.

Increasing angle values go **clockwise** around the circle. Another way of thinking about this is that the result of sin() is inverted to match the orientation of the y-axis, with increasing y values going down the display. See sin() and atan2() for further explanation.

For more information:

* The Math section of the API reference
* Information of operators

## Approximating log

PICO-8 does not have a built-in logarithm function. You can create one based on a lookup table, adjusted for your desired level of accuracy. Here's a simple log-base-10 function:

```
log10\_table =
{
  0, 0.3, 0.475,
  0.6, 0.7, 0.775,
  0.8375, 0.9, 0.95, 1
}

function log10(n)
  if (n < 1) return nil
  local t = 0
  while n > 10 do
    n /= 10
    t += 1
  end
  return log10\_table[flr(n)] + t
end

for x=5,500,10 do
  printh('log10('..x..') = '..log10(x))
end

```

This function takes advantage of the facts that `log10(a * b) = log10(a) + log10(b)`, and `log10(10^t) = t`. It divides the value by 10 repeatedly until the value is between 1 and 10, keeping track of the number of divisions (`t`). It uses a lookup table to approximate the log of the value in this range, then adds in the log of the 10's. You can change the base by replacing "10" with the new base wherever you see it, and changing the table with new approximations for the integers from 1 to 10.

For more accuracy, you can always use larger lookup tables, but at some point you're better off calculating the logarithm directly:

```
function log10(n)
  if (n <= 0) return nil
  local f, t = 0, 0
  while n < 0.5 do
    n \*= 2.71828
    t -= 1
  end
  while n > 1.5 do
    n /= 2.71828
    t += 1
  end

  n -= 1
  for i = 9, 1, -1 do
    f = n\*(1/i - f)
  end
  t += f
  -- to change base, change the
  -- divisor below to ln(base)
  return t / 2.30259
end

```

The above operates similarly to the lookup-table algorithm: first it finds a rough approximation by dividing `n` and incrementing `t`, then it adds a number to fine-tune the approximation. The difference is in how they do the fine-tuning: whereas the first algorithm uses a lookup table, the second algorithm uses a polynomial based on the natural logarithm's Taylor series. The result is still an approximation, but a much more accurate one: this function is correct to 3 decimal places, and often to 4. Changing the base only requires looking up `ln(base)` and replacing the single number at the end of the function.

Keep in mind that the PICO-8 number type has a positive max of 32767, so that's your effective domain. log10(32767) is 4.51543..., so that's your range. You may want more digits of accuracy if you're doing a lot of work within that domain.
GettingStarted

(I intended to put a full PICO-8 starter tutorial here. Until I or someone else does, here are links to some resources to get started.)

## Resources

Dylan Bennett's Game Development with PICO-8 is a zine. The first issue introduces the major topics and walks through some examples.

The PICO-8 Zine is a collection of articles and tutorials on PICO-8 subjects, written by multiple authors and edited by Arnaud DeBock. Most articles are intended for beginners.

Some people have made video tutorials and uploaded them to YouTube:

* Matt Tuttle's PICO-8 Tutorials
* TeamWorkCast's PICO-8 Hero
* Gruber's PICO-8 Music Tutorials
* Jason's PICO-8. The Basics

## Books

Tassilo Rau's How to Make Games With PICO-8 was being worked on, and users could pre-order the book and get early access to drafts.

The project stopped being updated during 2018 because of family health issues, and unrelated to that the author passed away unexpectedly late 2019.
Mget

mget( celx, cely )
Gets the sprite number assigned to a cell on the map.
celx

The column (x) coordinate of the cell.

cely

The row (y) coordinate of the cell.

The `mget()` function returns the sprite number assigned to a cell on the map. If a cell was modified by a call to `mset()`, `mget()` returns the updated value.

When using the map to store level designs, a common technique is to keep track of the player's effective cell position on the map, then use `mget()` to look for adjacent level features such as obstructions. This can be combined with sprite flags (read with `fget()`) to indicate which sprite tiles represent obstructions, so a general purpose test for obstructions only needs to read the flags.

## Examples

```
to\_the\_right = mget(player.celx + 1, player.cely)

```

## Notes

This function works only when the tiles are drawn by `map()` function.

## See also

* Graphics
* `fget()`
* `fset()`
* `map()`
* `mset()`
* `pget()`
* `pset()`
* `sget()`
* `sset()`
Iris13

**￼Iris13** - użytkowniczka Momio. Jest znana głównie dzięki swoim editom i kanałowi na YT (którego już nie prowadzi i w najbliższym czasie nie ma zamiaru). Nie gra od mniej więcej początku roku 2020.

## Historia

Była w jakikolwiek sposób znana dzięki swojemu instagramowi poświęconego editom z Momio, oraz kanale na youtube, (których nie prowadzi już od dłuższego czasu).

## Ciekawostki

* Podpisywała się na editach pseudonimem Makao
* Miała kiedyś konto słika, ale zostało jej ukradzione i usunięte
* Ma na imię Zuza
* Jej marzeniem gdy jeszcze grała było zostać SMA lub Momio Designerem
* Jest fanką starej muzyki, najczęściej rockowej (m.in. Dżemu, Queen.)
* Lubi oglądać anime
* Ma bardzo dużo znajomych, przez co miewa lagi ale jest zbyt leniwa, żeby zrobić porządki
* **6 grudnia 2018 roku jej edit (animo) pojawił się na Momio, w paczce.**

## Social Media/Inne serwery

* **Instagram** - anozuma (obecny)
* **Instagram** - makaoedits (usunięty)
* **Angielski Serwer** - Makao (nie gra)
Split

split( str, [separator,] [convert\_numbers] )
Split a string into a table of elements delimited by the given separator (defaults to ",").
str

The string.

separator

The separator (defaults to ",").

convert\_numbers

When convert\_numbers is true, numerical tokens are stored as numbers (defaults to true).

The `split()` function splits a string into a table of elements delimited by the given separator (defaults to ",").

Empty elements are stored as empty strings.

When the separator is "", every character is split into a separate element.

The separator can also be a number (say, N), in which case - the function splits the string after every N characters.

## Examples

```
split("1,2,3") -- returns {1,2,3}
split("one:two:3",":",false) -- returns {"one","two","3"}
split("1,,2,") -- returns {1,"",2,""}
split("12345",2) -- returns (12,34,5)

```

## See also

* Lua
* Tables
Yet Another Multiple States System

## Description

This will give you an easy way to keep the code separate for your game's different states (such as menu screen, gameplay, and game over screen). It's easy to manage, easy to add to, and easy to understand again when you come back to your code months later and want to figure out what does what.

This is a different method of achieving the same result as the Multiple States System guide.

## Instructions

The basic idea is that alongside the built-in \_init(), \_update(), and \_draw() functions, you create a different set of **`init()`**, **`update()`**, and **`draw()`** functions for each state you need in your game. This system relies on the useful fact that Lua variables can hold function names.

For this example, we'll start with the **`menu`** state, and then add the **`game`** state so you can see how easy it is to add new states. To create your game's **`menu`** state, write the following:

```
function \_init()
 menu\_init()
end

function \_update()
 update()
end

function \_draw()
 draw()
end

function menu\_init()
 update=menu\_update
 draw=menu\_draw
end

function menu\_update()
end

function menu\_draw()
end

```

### Adding Another State

Now if you want to add a game state, you just add the following three functions:

```
function game\_init()
 update=game\_update
 draw=game\_draw
end

function game\_update()
end

function game\_draw()
end

```

### Switching States

To switch to the **`game`** state, all you need to do is call **`game_init()`**. For example, the menu's **`menu_update()`** function might look like this:

```
function menu\_update()
 if (btn(4)) game\_init()
end

```

When the game is over, you could just call **`menu_init()`** to go back to the menu.

## Further Tweaks

Since you won't ever be doing much with the built-in game loop functions, you can optionally condense them down into the following 3 lines of code:

```
 function \_init() menu\_init() end
 function \_update() update() end
 function \_draw() draw() end

```

(This just takes up less space in the editor. It doesn't actually do anything different)
Graphics

## Palette

PICO-8 starts up with both the draw and screen palettes set to the following indices & colors, with index 0 flagged as transparent in sprites and maps:

 4
 8
 12

The *draw palette* may be altered by calling pal(draw\_palette\_index, screen\_palette\_index). This allows remapping sprite and map colors.

The draw palette's *transparency* flags may be altered by calling palt(draw\_palette\_index, true/false). This allows cookie-cutter style transparency in sprites and maps.

The *screen palette* may be altered by calling pal(screen\_palette\_index, system\_palette\_index, 1). This allows rearranging the default colors, or swapping in some of the undocumented alternate colors in the range 128-143:

 132
 136
 140

See Palette for many more details, as well as the specific RGB values for each palette color, which may be useful in external editors or on the web.

## Functions

* `camera([x,] [y])`
* `circ(x, y, r, [col])`
* `circfill(x, y, r, [col])`
* `clip([x,] [y,] [w,] [h])`
* `cls()`
* `color(col)`
* `cursor(x, y)`
* `fget(n, [f])`
* `fillp([pat])`
* `fset(n, [f,] [v])`
* `line(x0, y0, x1, y1, [col])`
* `pal([c0,] [c1,] [p])`
* `palt([c,] [t])`
* `pget(x, y)`
* `print(str, [x,] [y,] [col])`
* `pset(x, y, [c])`
* `rect(x0, y0, x1, y1, [col])`
* `rectfill(x0, y0, x1, y1, [col])`
* `sget(x, y)`
* `spr(n, x, y, [w,] [h,] [flip_x,] [flip_y])`
* `sset(x, y, [c])`
* `sspr(sx, sy, sw, sh, dx, dy, [dw,] [dh,] [flip_x,] [flip_y])`

See also API Reference.
Update

The first part of a game loop is normally an *update*. In PICO-8, this is done with either an `_update()` function, for 30fps games, or `_update60()` for 60fps games.

If a cartridge's source code includes both an `_update()` function and a `_draw()` function, then PICO-8 will attempt to call these functions once for each animation frame, at a rate of 30 frames per second for `_update()` or 60 frames per second with with `_update60()`.

You define this function in your game's source code. It takes no arguments.

The intended purpose of `_update()` is to test for user inputs (button presses), perform all of the calculations to advance the state of the game, and update the game's data structures with the results. For example, you might compare the state of variables to see if the player's avatar is near an item during `_update()`. Typically, this function does not update the display, though it may initiate sound effects and music.

See the entry on the game loop.

## Examples

```
player\_x=64
player\_y=100

function \_update()
  if(btn(0)) player\_x-=1
  if(btn(1)) player\_x+=1
end

```

## See also

* game loop
* `\_init()`
* `\_draw()`
* `music()`
* `sfx()`
* ``stat()``
Reload

reload( destaddr, sourceaddr, len, [filename] )
Loads a region of data from the cartridge, or from another cartridge, into memory.
destaddr

The address of the first byte of the destination in memory.

sourceaddr

The address of the first byte in the cartridge data.

len

The length of the memory region to copy, as a number of bytes.

filename

If specified, the filename of a cartridge from which to read data. The default is to read from the currently loaded cartridge.

The `reload()` function copies data from the cartridge into a location in memory.

Cartridge data is copied to memory addresses 0x0000-0x4300 when the cartridge is loaded for the first time. After that point, the program is allowed to modify memory with `memcpy()`, `poke()`, `mset()`, `sset()`, or `fset()`. These operations do not modify the original cartridge data. You can use `reload()` to restore modified data, or otherwise access data that has been overwritten in memory.

If the optional filename argument is provided, `reload()` will attempt to load from that cartridge file, which does not need to be the currently loaded cartridge. You can use this to store large amounts of game data over multiple cartridges.

`reload()` is equivalent to `reload(0, 0, 0x4300)`.

The memory layout for cartridge data is identical to PICO-8 memory for the address region 0x0000-0x4300. See Memory for an explanation of memory and cartridge data, and for a description of the memory layout.

Note: When loading data from a named file, the current cart must be saved to disk. If `reload()` is called with a filename but it appears to be loading from the current cart instead, try saving the current cart with a name, rebooting, and reloading the cart.

## Examples

Consider a game that stores the locations of collectible treasures in the map data, and removes them from the map with `mset()` when the player collects them. To reload the original map data from the cartridge:

```
-- for a 128x64-tile map that can only use the first 128 sprite tiles
reload(0x1000, 0x1000, 0x2000)

-- for a 128x32-tile map that can use all 256 sprite tiles
reload(0x2000, 0x2000, 0x1000)

```

Consider a game that uses very large maps stored in multiple cartridges. To load the map for a new area from cartridges stored in carts named `"biggame_lvl1.p8"`, `"biggame_lvl2.p8"`, etc.:

```
function load\_area(lvl)
  reload(0x1000, 0x1000, 0x2000, 'biggame\_lvl'..lvl..'.p8')
end

load\_area(2)

```

## See also

* Memory
* `peek()`
* `poke()`
* `memcpy()`
* `cstore()`
* `memset()`
Matt Versus Slenderman

Creator
 Genre
 Player Count

## Description

The player controls Matt, who must collect several pages while avoiding Slenderman.

## Rules

* Matt must explore several locations in order to find several pages. Places can be accessed by walking, jumping, entering/exiting doors and collecting keys.
* Slenderman is one of the several hazards of the game; the player is alerted to his presence by appearing via split-second cutscene. Slenderman will then usually appear onscreen in the game. If Matt continues facing him for a couple of seconds that will end the game, along with coming into contact with him and a grim reaper character if all pages are found. Falling into pits, water and being impaled on spikes will also end the game. There is also several multi-colored objects in the castle that, if Matt makes contact with one of them, will turn all onscreen platforms into water, which will end the game if Matt falls into them (especially if any of the areas have spikes underneath them).
* Turning away from Slenderman for 1.5 seconds will cause him to disappear.
* There are three ways to play: regular, turbo (with Matt, the grim reaper and the crawling Slenderman moving at a very fast pace), and starting a game where Matt is positioned at a different starting place.
* Once the fifth page is collected, beware! Slenderman will appear in a different, fast-moving form and could head straight for Matt.
* Unlike how the game states, there are actually nine pages to be found in order to get to the end of the game.

## Controls

* At the title screen, use the z (normal play mode), x (turbo) or arrow keys (start game in different area) to start a new game.
* Use the x key to view last page collected.
* Use the z key to jump.
* Use the arrow keys to move.
* Use the up or down arrow keys to enter a door or below ground area.
* Use the p or Enter key to pause the game.
Shl

Superseded / Deprecated
The feature described in this article has been superseded by a newer feature. This feature still works in PICO-8, but the new feature should be used instead. See the article's "Superseded by..." section for specific details.

shl( num, bits )
Shifts the bits of a number to the left.
num

The number.

bits

The number of bits to shift.

The `shl()` function takes a number and a bit count, and returns the result of shifting the bits of the number to the left by that count.

Numbers in PICO-8 are stored using a 32-bit *fixed point* format, with 16 bits for the integer portion, 16 bits for the fractional portion, and a twos complement representation for negative and positive values. Bit shifting uses the entire number representation. (See examples below.)

## Superseded by << operator

The `<<` operator added in 0.2.0 performs the same function as `shl()` and is now the recommended way to shift bits left, as it uses fewer tokens, costs fewer cycles at runtime, and runs on the real host CPU much more efficiently. Simply replace `shl(a,b)` with `a<<b`.

## Examples

```
-- 1 = 00000001 binary
-- 8 = 00001000 binary
print(shl(1, 3))      -- 8

-- 0.125 = 0000.0010 binary
-- 1.000 = 0001.0000 binary
print(shl(0.125, 3))  -- 1

print(1 << 3)         -- 8, preferred method

```

## See also

* Math
* `band()`
* `bor()`
* `bxor()`
* `bnot()`
* `lshr()`
* `shr()`
* `rotl()`
* `rotr()`
Stop

stop( [message,] [x,] [y,] [col] )
Stops the program's execution and returns to the command prompt.
message

An optional message to print before stopping.

x

The x coordinate of the upper left corner to start printing.

y

The y coordinate of the upper left corner to start printing.

col

The color to use for the text.

Undocumented feature
This article describes a feature that is not mentioned in the official Pico-8 documentation. The feature was known to work at the time the article was written, but
it may be removed or changed in a future version.

The `stop()` function stops the program at the point where the function is called, returning to the command prompt. This is similar to pressing the Escape key at a specific point in the code.

Note that the format of the optional arguments is identical to the more-familiar `print()`. This can be useful for explaining why the app has exited, especially if combined with information from `trace()`.

If your program uses the game loop, you can resume execution of the program using the `resume` command. This does *not* resume from the call to `stop()`. Instead, it starts the next loop iteration with a call to `\_update()`. If your program does not use the game loop, `resume` raises an error.

## Examples

```
v = 1

function \_update()
  v += 1
  if (v % 5) == 0 then stop() end
end

function \_draw()
  cls()
  print(v, 0, 0, 8)
end

```

Running this program stops when `v` is a multiple of 5. From the command prompt:

```
> print(v)
5
> resume

```

The program stops again at the next multiple of 5:

```
> print(v)
10

```

## See also

* Game loop
* `resume`
* `assert()`
Pico8Slack

The PICO-8 community uses Slack for real-time discussion and collaboration. The "pico-8" Slack group has active users and multiple channels.

http://pico-8.slack.com/

To join this Slack group, sign up for Slack, then enter your email address in this form:

https://slofile.com/slack/pico-8

You will be invited to the Slack group automatically.

Discussion: http://www.lexaloffle.com/bbs/?tid=2732

There is also another Slack group called "picocity": https://slofile.com/slack/picocity http://www.lexaloffle.com/bbs/?tid=3157

The Fantasy Consoles Discord server has a PICO-8 channel, as well as channels for other fantasy consoles inspired by PICO-8 and otherwise. The community runs regular game jams: http://discord.gg/sFeDxWK
Cos

cos( angle )
Calculates the cosine of an angle.
angle

The angle, using a full circle range of 0.0-1.0.

The `cos()` function calculates the cosine of an angle.

PICO-8 uses an input range of 0.0 to 1.0 to represent the angle, a percentage of the unit circle. Some refer to these units as "turns". For instance, 180° or π (3.14159) radians corresponds to 0.5 turns in PICO-8's representation of angles. In fact, for fans of τ (tau), it's just a matter of dropping τ from your expression.

**Important:** PICO-8 measures the angle in a *clockwise* direction on the Cartesian plane, with 0.0 to the right, 0.25 downward, and so on. This is inverted from the convention used in traditional geometry, though the inversion only affects `sin()`, not `cos()`.

## Examples

```
for t=0,1,0.125 do
  print('cos('..t..') = '..cos(t))
end

```

prints:

```
cos(0) = 1
cos(0.125) = 0.7071
cos(0.25) = 0
cos(0.375) = -0.7071
cos(0.5) = -1
cos(0.625) = -0.7071
cos(0.75) = 0
cos(0.875) = 0.7071
cos(1) = 1

```

## See also

* Math
* `sin()`
* `atan2()`
Memcpy

memcpy( destaddr, sourceaddr, len )
Copies a region of memory to another location in memory.
destaddr

The address of the first byte of the destination.

sourceaddr

The address of the first byte of the memory to copy.

len

The length of the memory region to copy, as a number of bytes.

The `memcpy()` function quickly copies one region of addressable memory to another. The origin region and the destination region may overlap.

See Memory for information about the memory layout.

## Examples

```
memcpy(0x5e00, 0x4300, 128)

```

## See also

* Memory
* `peek()`
* `poke()`
* `reload()`
* `cstore()`
* `memset()`
Camera

camera( [x,] [y] )
Sets the camera offset in the draw state.
x

The x pixel offset to be *subtracted* from future draw coordinates. Default is 0.

y

The y pixel offset to be *subtracted* from future draw coordinates. Default is 0.

*return-value*

An x,y tuple representing the previous camera offset.
Setting a camera offset causes all subsequent draw operations to have the offset *subtracted* from their x and y coordinates. Camera sets the origin point for draw functions, and by default it is `(0,0)`.

The way `camera()` works is somewhat unintuitive. So, if you might expect to use `camera(64,64)` to put the camera origin in the middle of the screen, you'd actually use `camera(-64,-64)` to move the screen so that its middle is in front of the camera. This is probably because `camera()` sets a screen variable that is invisibly used by all draw functions, and in this case, the origin changed from `(0,0)` to `(-64,-64)`.

Camera offsets can be used to implement screen effects such as parallax scrolling (with a different offset per layer) or screen shake (a small random offset per frame).

## Technical notes

The current camera offset is memory-mapped and may be read or written directly:

* 0x5f28 / 24360: offset x lo byte
* 0x5f29 / 24361: offset x hi byte
* 0x5f2a / 24362: offset y lo byte
* 0x5f2b / 24363: offset y hi byte

## Examples

```
-- draw a dark blue circle at (20, 20)
circfill(20, 20, 10, 1)

camera(-2, 2)

-- draw a white circle at (22, 18)
circfill(20, 20, 10, 7)

camera(-64, -64)

-- draw a big red circle, centered
circfill(0, 0, 63, 8)

-- get the current offset from its memory-mapped addresses
camera\_x = peek2(0x5f28)
camera\_y = peek2(0x5f2a)

```

## See also

* Graphics
* Draw state
* `clip()`
Bnot

Superseded / Deprecated
The feature described in this article has been superseded by a newer feature. This feature still works in PICO-8, but the new feature should be used instead. See the article's "Superseded by..." section for specific details.

bnot( num )
Calculates the bitwise not of a number.
num

The number.

*return-value*

The bitwise-not of num.
The `bnot()` function inverts all of the bits of a number.

Numbers in PICO-8 are stored using a 32-bit *fixed point* format, with 16 bits for the integer portion, 16 bits for the fractional portion, and a twos complement representation for negative and positive values. As a result, the bitwise-not of a number tends to be its negative. (`bnot(0)` is almost 0, but not quite.)

In cases where you're using `bnot()` you probably only care about specific bits and not the entire number. You can `band()` the result to mask out the bits you don't care about.

## Superseded by ~ operator

The unary `~` operator added in 0.2.0 performs the same function as `bnot()` and is now the recommended way to invert bits, as it uses fewer tokens, costs fewer cycles at runtime, and runs on the real host CPU much more efficiently. Simply replace `bnot(a)` with `~a`.

## Examples

```
-- 0xb = 000...1011
-- not 0xb = 111...0100
-- 0xf = 000...1111
-- (not 0xb) and 0xf = 000...0100 (0x4)
print(band(bnot(0xb), 0xf))  -- 4

print(bnot(0xb))             -- -11 (0 - 0xb)

print(~0xb)                  -- preferred method

```

## See also

* Math
* `band()`
* `bor()`
* `bxor()`
* `lshr()`
* `shl()`
* `shr()`
* `rotl()`
* `rotr()`
Cartdata

cartdata( id )
Sets up cartridge data for the cart.
id

A string that is likely to be unique across all PICO-8 carts.

A cartridge can store 64 numbers (256 bytes) of data to persistent storage. This data is available the next time the user runs the cart, and persists in the player even if the cartridge is replaced with a new version of the same cartridge.

The `cartdata()` function sets up PICO-8's persistent cartridge data feature. It must be called once (and only once) by the cart before using `dset()` or `dget()`.

The function takes a string ID that uniquely identifies the cartridge among all PICO-8 cartridges that might have persistent data. There is no central registry for cartdata IDs, and you're expected to not willfully overwrite data belonging to other carts. Likewise, you can purposefully use the same ID across multiple carts to share persistent data between carts, such as to implement a very large adventure game that requires multiple carts.

One reasonable way to derive a unique ID for your cart is to use the following pattern:

`username_title_version`

... where `username` is your PICO-8 BBS username, `title` is the title of the cartridge, and `version` is an optional version ID. You would only increment the version ID if a new version of the cart stores cart data in a format incompatible with previous versions.

Once `cartdata()` has been called, the data bytes can be accessed directly at memory locations 0x5e00 to 0x5eff. Using `poke()` to update these values persists the new value automatically, similar to `dset()`.

The function returns true if the data was found and loaded, or false if the data wasn't found and was created instead. This can be used to determine whether to load from the data or to initialize it.

## Examples

```
function \_init()
  cartdata("zep\_jelpi\_1")
  player\_pos = dget(0)
  player\_inventory = dget(1)
end

function save\_game()
  dset(0, player\_pos)
  dset(1, player\_inventory)
end

```

## See also

* Memory
* `dget()`
* `dset()`
Picotool

picotool is a suite of tools and a Python library for manipulating PICO-8 cartridges.

* picotool on Github

The tool suite includes commands for gathering statistics, inspecting contents, minifying or formatting Lua code, and searching for strings in the Lua code of multiple carts. The tools can read .p8.png carts as well as .p8 carts.

The picotool library can read .p8 and .p8.png cartridges, and can save .p8 cartridges. It includes a full Lua parser tailored to match PICO-8, with Python access to the token stream and AST. Other libraries provide read/write access to graphics, music, and sound data, as well as arbitrary access to cartridge binary data.

The p8upsidedown tech demo uses the picotool library to invert a cartridge's graphics, map, music, and controls so that the cart plays upside down. This demo modified both the data and the code to accomplish this effect.
Pico8Zine

The PICO-8 Zine is a periodical of articles about PICO-8 written by members of the community. The zine is organized and published by arnaud\_debock. Issues are available for free as a downloadable PDF, or in print in limited quantities for a small fee.

http://pico8fanzine.bigcartel.com/

## Issue #1

PDF, print, forum discussion

Contents:

* A Brief History of PICO-8, by zep
* Squashy, by Alex Mole (@TheRealMolen)
* Let's Make Some Music, by Feliks Balzer
* Toy Train, by James (PROGRAM\_IX)
* Geodezik, by @aliceffekt
* Smoke Particle, by Mozz
* Welcome to PICO-8!, by @terrycavanagh

## Issue #2

PDF, print, forum discussion

Contents:

* Hello everyone, by Arnaud DE BOCK
* Game Of Life, by dddaaannn (@dan\_sanderson)
* 3d demo, by @NoahRosamilia
* Shrinking your code, by Jonathan Stoler (@jonstoler)
* Shodo, by @oinariman
* Water Waves, by Matthew Klundt
* Screensaver, by Devine Lu Linvega (@aliceffekt)
* PicoJump, by Johannes Richter
* Color palette, by Gabby DaRienzo

## Issue #3

PDF, print, forum discussion

Contents:

* Minimalism Pays Double, by Matt (@MattThorson)
* Notes on Creating Succer, by Laury MICHEL (@RylauChelmi)
* Dom8verse, by @schminitz
* Minigame Collection, by Jack Harrison (@jhrrsn)
* Blasteroids, by Lulu Blue (@luluisbluetoo)
* Sumo Pico, by Cullen Dwyer (@cullenddwyer)
* Cheat Sheet, by @obono

## Issue #4

PDF, print, forum discussion

Contents:

* DON'T WAIT, by Michael Brough (@smestorp)
* AI MOVE SPECIAL ROGUELIKE, by Benjamin Soule (@benjamin\_soule\_)
* A\* pathfinding in PICO-8, by Richard Adem (@richy486)
* Traps For Absolutely Every Imaginable Occasion, by Kyle Reimergartin (@mooonmagic)
* The Roguelike \*shiny\* game-feel, by Dog Trasevol (@TRASEVOL\_DOG)
* Dungeon walls, by Rodrigo Franco (@caffo)
* Sharing music between carts, by Robby (@RobbyDuguay)
* DONUT MAZE, by zep (@lexaloffle)

## Issue #5

Issue #5 is currently in progress (forum discussion).
Sspr

sspr( sx, sy, sw, sh, dx, dy, [dw,] [dh,] [flip\_x,] [flip\_y] )
Draws a rectangle of pixels from the sprite sheet, optionally stretching the image to fit a rectangle on the screen.
sx

The x coordinate of the upper left corner of the rectangle in the sprite sheet.

sy

The y coordinate of the upper left corner of the rectangle in the sprite sheet.

sw

The width of the rectangle in the sprite sheet, as a number of pixels.

sh

The height of the rectangle in the sprite sheet, as a number of pixels.

dx

The x coordinate of the upper left corner of the rectangle area of the screen.

dy

The y coordinate of the upper left corner of the rectangle area of the screen.

dw

The width of the rectangle area of the screen. The default is to match the image width (sw).

dh

The height of the rectangle area of the screen. The default is to match the image height (sh).

flip\_x

If `true`, the image is drawn inverted left to right. The default is `false`.

flip\_y

If `true`, the image is drawn inverted top to bottom. The default is `false`.

This operation is affected by the draw state.

Unlike `spr()`, this function uses pixel locations on the sprite sheet instead of sprite numbers. The sprite sheet is treated as an image 128 pixels wide and 128 pixels high, where (0, 0) is the upper left corner.

If you know the sprite number **sp**, you can get its coordinates in the sprite sheet **(sx, sy)** using this formula:

```
sx, sy = (sp % 16) * 8, (sp \ 16) * 8

```

This is because the sprite sheet has 16 sprites per row and each sprite is 8x8.

## Examples

```
-- draw the 8 x 8 image from (8, 0) at screen location (60, 60)
sspr(8, 0, 8, 8, 60, 60)

-- draw the same image but stretched to 12 x 20 at screen location (44, 48)
sspr(8, 0, 8, 8, 44, 48, 12, 20)

-- draw it again, flipped horizontally, at (72, 48)
sspr(8, 0, 8, 8, 72, 48, 12, 20, true, false)

```

This example appears to distort the original image differently based on whether the image is flipped. Notice that the stretched image must still use the 128 x 128 resolution of PICO-8. To stretch from 8 pixels to 12, `sspr()` doubles the width of every other column. Because of how this sprite is drawn, the flipped version puts the features of the image (hair, face, arms) on different columns, so different features get double-wide in the flipped version.

## See also

* Graphics
* Draw state
* `pal()`
* `palt()`
* `spr()`
* `tline()`
Prism

The prism is probably the most unused token in ChessAdventures. It is a "dead" token, which means the only reason for it still beign in the game is for backwards compatibility. It is one of the rideable tonkens, which meats wheels can be installed on it, and it can be mounted.

## Trivia

The prism was added to ChessAdventures with the purpose to split laser, like obsidian does but before obsidian existed. Later when obsidian was added, which made the prism almost useless. In an attempt to keep the prism relevant the "Prism material" option was added. But today it's considered a dead token.
Set fps

\_set\_fps( rate )
Set the target framerate.
rate

The target framerate: 15, 30, or 60.

This internal, undocumented function is how the PICO-8 application sets the target frame rate.

When the user's code is first run, PICO-8 is in 30fps mode. Typically, the user's code will be run through, without any actual drawing being done, and then control will return to the hidden outer code that will then begin to call `_update()` and `_draw()` repeatedly.

At the point where the outer code takes over, it will check for the presence of either `_update()` or `_update60()` and then call either `_set_fps(30)` or `_set_fps(60)`, respectively.

If, however, the user wishes to do some drawing before control returns to the outer code, they may change the default frame rate with this function and then create their own custom main loop that updates, draws, and calls `flip()`, repeatedly.

## Note on 15fps mode

This mode is really most practical when calling `_set_fps(15)` from root user code, and then doing all updating and rendering with a custom main loop. Otherwise the outer code will take over and assign either 30fps or 60fps mode, depending on which functions are implemented.

However, if `_set_fps(15)` is called from within `_update()` (note that `_init()` is too early), then the outer code will begin to call `_update()` twice for every call to `_draw()`, effectively halving the draw rate to 15fps. This is both klunky and unsupported, so it would generally be better just to use standard 30fps mode and return early from every other `_draw()` call.

## Warning

As an undocumented function, `_set_fps()` cannot be relied on for a game. Its functionality may change or be removed in future versions. Still, some may find a pragmatic use for it in tools or demos. Just be aware that you use it at your own risk.

## Examples

```
-- make a reddish orange by rapidly alternating red and orange at 60fps
\_set\_fps(60)
while true do
  cls(8) -- red
  flip()
  cls(9) -- orange
  flip()
end

-- wait for 1 second at 15fps
\_set\_fps(15)
for i=1,15 do
  flip()
end

```
Help

help [topic]
Displays a brief message about available commands.
topic

A specific topic. Default is general usage.

Used at the command prompt to display brief help on using and programming PICO-8.

Without args, `help` provides some general usage information and tips on digging deeper.

With a supplied topic, `help` can provide detailed info on specific commands, API functions, and several broad categories: `gfx`, `data`, `audio`, `system`, `math`, and `lua`.

## Examples

To get general usage and tips on using `help`:

```
> help

```

Or, to view information on categories or individual commands and functions:

```
> help audio

█ audio api functions

music sfx

> help music

█ music(p,[fade_len],[mask])

play music starting from pattern
p. use p -1 to stop any music.

fade_len is given in ms (1000 is
one second). mask is a bitfield
used to specify which channels
to reserve for music.

```
Config

config [setting] [value]
Modify the configuration settings.
setting

The name of the setting, e.g. `theme`. If absent, available settings are listed.

value

The new value for the setting. If absent, the current value is printed.

This is a way to modify the PICO-8 configuration live at runtime, within the PICO-8 environment. Changes will be saved to PICO-8's configuration file.

Run the command with no arguments to see the names of the available settings.

Run the command with the name of a setting to see its current value and info on how to change the value.

Run the command with both the name of a setting and a new value to change the setting.

## Examples

At the Pico-8 prompt, discovering available settings:

```
> config
config [setting]

available settings:
volume
theme
gif_len
screenshot_scale
splore_filter
tab_width
draw_tabs

```

Examining and modifying the tab width setting:

```
> config tab_width
config tab_width [width]
current tab_width: 1

> config tab_width 2
set tab_width: 2

```

## See also

* `keyconfig`
* Configuration