recursal/Fanatic-Fandom huggingface dataset:
Clipboard

PICO-8 allows access to the system clipboard, both through its editors and with Lua code.

## Reading the clipboard with Lua

The system clipboard contents can be found using `stat(4)`, as a string:

```
print('clipboard: '..stat(4))

```

Caveat: Initially, `stat(4)` will return a blank string, even if there is data already on the system clipboard. The clipboard contents will only update under one of these conditions:

* The user presses the "paste" key sequence while Lua code is actively running. This is either Control-v (Windows, Linux) or Command-v (Mac OS X).
* A string is written to the clipboard by Lua inside the current PICO-8 instance.

This is to prevent a cartridge from accessing potentially-sensitive data on the host system's clipboard without the user's permission.

## Writing to the clipboard with Lua

A string may be written to the system clipboard with `printh()`, so you can paste it into another program interactively. To do this, provide a `filename` of `'@clip'`:

```
printh('collision data: xpos='..xpos..' ypos='..ypos, '@clip')

```

Each call to `printh(..., '@clip')` completely replaces the contents of the system clipboard with the given string. There is no way to append the string to the existing contents. As such, you must use the existing clipboard contents before the next call to `printh(..., '@clip')`.

NOTE: It is necessary to press CTRL+V in the Pico-8 task you have open in order to PASTE the clipboard's contents to that task so it may be read by STAT(4). You must do this each time now.

## Editor clipboard formats

The sprite editor reads and writes rectangular image data to the clipboard, formatted as a string of hexadecimal characters, like so:

```
[gfx]WWHHPPPPP...PPP[/gfx]

```

With:

* WW = width in hex (`01..80`, or 1..128 in decimal)
* HH = height in hex (`01..80`, or 1..128 in decimal)
* P = pixel in hex (`0..f`, or 0..15 in decimal)

There should be `WW * HH` pixels encoded in the string.

When creating strings to for pasting into the sprite editor, be aware that newlines and any other characters that are not hexadecimal values will be treated as "0" (black) pixels.
Tline

*New in PICO-8 0.2.0.*

tline( x0, y0, x1, y1, mx, my, [mdx,] [mdy] )
Draws a textured line between two points, sampling the map for texture data.
x0

The x coordinate of the start of the line.

y0

The y coordinate of the start of the line.

x1

The x coordinate of the end of the line.

y1

The y coordinate of the end of the line.

mx

The x coordinate to begin sampling the map, expressed in (fractional) map tiles.

my

The y coordinate to begin sampling the map, expressed in (fractional) map tiles.

mdx

The amount to add to mx after each pixel is drawn, expressed in (fractional) map tiles. Default is 1/8 (move right one map pixel).

mdy

The amount to add to mx after each pixel is drawn, expressed in (fractional) map tiles. Default is 0 (a horizontal line).

The `tline()` function draws a line while sampling colors from the map to provide a texture for the line. The mx and my parameters are similar to u,v coordinates used in 3D texture mapping, with the exception that they are expressed in units of map tiles. For example, a coordinate of 4.5,10 would sample from the pixel at 4.5\*8,10\*8 = 36,80 in the map.

The mdx and mdy parameters are effectively the slope of the line being sampled in the map. They can be fractional, they can be negative, and they can be 0. If both are 0, the whole line will sample from the same pixel on the map.

The map coordinates (mx, my) are masked by values calculated by subtracting 0x0.0001 from the values at address 0x5f38 and 0x5f39. In simpler terms, this means you can loop a section of the map by poking the width and height you want to loop within, as long as they are powers of 2 (2,4,8,16..)

For example, to loop every 8 tiles horizontally, and every 4 tiles vertically:

```
poke(0x5f38, 8)
poke(0x5f39, 4)

```

The default values of (0,0) gives a mask of 0xff.ffff causing the samples to loop every 256 tiles.

To choose the offset where the loop starts from (in tiles), use addresses 0x5f3a and 0x5f3b:

```
poke(0x5f3a, offset\_x)
poke(0x5f3b, offset\_y)

```

## Examples

```
-- draw 20 textured lines in random locations,
-- sampling from the first pixel row of the map
for x=1,20 do
  tline(rnd(128), rnd(128), rnd(128), rnd(128))
end

-- draw 20 textured lines in random locations,
-- sampling from the tenth pixel column of the map
for x=1,20 do
  tline(rnd(128), rnd(128), rnd(128), rnd(128), 10/8, 0, 0, 1/8)
end

```

## See also

* Graphics
* Draw state
* `circ()`
* `circfill()`
* `line()`
* `map()`
* `rect()`
* `rectfill()`
Lshr

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.

lshr( num, bits )
Shifts the bits of a number to the right, using logical shift.
num

The number.

bits

The number of bits to shift.

The `lshr()` function takes a number and a bit count, and returns the result of shifting the bits of the number to the right by that count. This uses a "logical shift."

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.)

`lshr()` performs a "logical shift," which shifts all of the raw bits of the number, filling the highest bits with zeroes. The alternative to logical shift is "arithmetic shift." See shr().

## Superseded by >>> operator

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

## Examples

```
-- 8 = 0b00001000 binary
-- 1 = 0b00000001 binary
print(lshr(8, 3))  -- 1

-- 1.000 = 0b0001.0000 binary
-- 0.125 = 0b0000.0010 binary
print(lshr(1, 3))  -- 0.125

-- -1.000 = 0b1111111111111111.0 binary (two's complement)
-- 8191.875 = 0b0001111111111111.111 binary
print(lshr(-1,3))  -- 8191.875

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

```

## See also

* Math
* `band()`
* `bor()`
* `bxor()`
* `bnot()`
* `shl()`
* `shr()`
* `rotl()`
* `rotr()`
Sget

sget( x, y )
Gets the color value of a pixel on the sprite sheet.
x

The x coordinate on the sprite sheet.

y

The y coordinate on the sprite sheet.

This is similar to `pget()` except instead of the graphics buffer, it gets the color value from the sprite sheet. The sprite sheet is treated as a single canvas 128 pixels wide and 128 pixels high.

If the bottom half of the sprite sheet is used for map data, `sget` will return map data values for that region. Prefer `mget()` for accessing map data.

It will return 0 (black) if given coordinates outside the range (0-127,0-127).

## Examples

```
sset(10, 10, 7)      -- sets (10, 10) to white
print(sget(10, 10))  -- prints 7

```

## See also

* Graphics
* `fget()`
* `fset()`
* `mget()`
* `mset()`
* `pget()`
* `pset()`
* `sset()`
Rey's Scavenger Run

Creator
 Genre
 Player Count

## Description

Taking place in the Star Wars The Force Awakens movie, the player controls one of the lead characters, Rey, who must scavenge "junk" to sell to her boss.

## Rules

* At the beginning of a game, Rey's boss instructs her what junk to pick up for him. The player then controls Rey in a speeder over a scrolling desert area as various objects appear. Rey must pick up several various junk pieces and reach the end of the level in order to progress to the next one.
* Along with junk pieces, various speeders need to be avoided that also appear throughout the game. Colliding with one will cause damage to Rey's speeder and if the player suffers too many collisions the game will end.

## Controls

* Use the X key to start a game and a level.
* Use the arrow keys to control Rey/her speeder.
* Use the Escape or Enter keys to pause the game.
Music

music( n, [fadems,] [channelmask] )
Plays a music pattern, or stops playing.
n

The pattern number to start playing (0-63), or -1 to stop playing music.

fadems

If not 0, fade in (or out) the music volume over a duration, given as a number of milliseconds.

channelmask

A bitfield indicating which of the four sound channels should be reserved for music. The default is 0 (no channels reserved).

A music pattern describes a part of a song to play as background music. The pattern assigns sound effects to one or more of the PICO-8's four sound channels, with instructions to proceed to the next pattern, loop, or end when the sounds end. Typically, sound effects associated with music patterns are a collection of notes played at the intended tempo.

A call to `music()` can include a *channel mask* to declare which sound channels should not be interrupted by a sound effect played by a call to `sfx()`. The channel mask is a bitfield, where channels 0, 1, 2, and 3 are represented by the corresponding bits, with values 1, 2, 4, and 8, respectively. A call to `sfx()` may still take over a channel reserved by the music pattern if it specifies an explicit channel number.

When using music and sound effects together, it is a good idea to set a channel mask that reserves some channels and leaves others open for effects. PICO-8 will prioritize the use of the unmasked channels for sound effects, giving both music and sound a chance to play.

It should be noted that it is only necessary to call `music()` once, to trigger playback. PICO-8 will continue playback independently afterwards. It is not necessary to call it every frame with the current music ID--in fact, doing so will cause the track to be stuck on the first note perpetually, as the music restarts over and over.

## Examples

```
-- start music from pattern 0
music(0)

-- stop the music with a 300 ms fade out
music(-1, 300)

-- start music from pattern 4, reserving channels 2 and 3
-- by setting bits 2 and 3, whose values are 4 and 8, totaling 12
music(4, 0, 12)

```
Poke

poke( addr, [value,] [...] )
Writes one or more bytes to contiguous memory locations.
addr

The address of the first memory location.

value

The byte value to write to memory. Defaults to 0.

...

Additional byte values to be written consecutively to memory.

The `poke()` function writes one or more bytes to the 16-bit-addressable memory region.

See Memory for information about the memory layout.

See `poke2()` for a way to write 16-bit values to groups of two consecutive memory addresses, and `poke4()` to write 32-bit values to groups of four consecutive memory addresses.

## Examples

```
poke(0x4300, 255)             -- write a byte to user RAM
poke(0x5f5c, delay, interval) -- set up btnp() intervals

```

## See also

* Memory
* `peek()`
* `peek2()`
* `peek4()`
* `poke2()`
* `poke4()`
* `memcpy()`
* `reload()`
* `cstore()`
* `memset()`
The Wee Dungeon

Creator
 Genre
 Player Count

## Description

Players must clear out dungeon rooms of creatures while collecting gold and various other items.

## Rules

* Players start at the bottom corner of a dungeon room. Due to having "impractical architecture", they must jump from platform to platform in order to make their way around. If they are able to make their way through a room, they will come to a door, which entering it will lead them to another room.
* Players fight various creatures along the way, which they can stab with their weapon. Defeating a creature will yield gold, possibly a health power-up and/or an item. Making contact with a creature will cost the player part of a heart meter (at the bottom of the screen) and the game will end when they are out of health. Making contact with a spike will also end the game if the player does not have a special item in their possession. A tally is then shown at the end of a game of how much gold was gathered and how many rooms were cleared.
* Most creatures just automatically move from side to side, although with the more rooms players clear, tougher monsters will start appearing that carry shields to block attacks with that are harder to defeat.
* Upon winning a battle, players will collect gold and possibly various items, such as a health power-up, which will increase their health. Special items include shields (which can block attacks), helmets, armor and a better weapon. These items can stop several attacks costing players their health, although they will disappear over time after they absorb too much damage. Landing on a spike will cost the player an item and give them a split second to try and make their way out of their current trap. Once a player obtains a stronger weapon and then loses it after it takes too much damage, they will revert back to their weaker default sword they started the game out with, whereas shields, armor and helmets will disappear entirely.
* Two players can play simultaneously.

## Controls

* Use the Z key to start a game.
* Use the left/right arrow keys to move player one and the S and F keys to move player two.
* Use the up arrow key to make player one jump and the E key to make player two jump.
* Use the Z key for player one to attack and the W key for player two to do the same.
* Use the X key for player one to use a shield (if applicable) and the Q key for player two's shield.
* Use the down arrow key for player one to enter a door and the D key for player two to do the same.
* Use the escape or Enter key to pause the game.
Band

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.

band( first, second )
Calculates the bitwise-and of two numbers.
first

The first number.

second

The second number.

*return-value*

The bitwise-and of first and second.
## Superseded by & operator

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

## Examples

```
-- 0x7 = 0111 binary
-- and 0xd = 1101 binary
-- -------
-- 0x5 = 0101 binary
print(band(0x7, 0xd))  -- 5

print(0x7 & 0xd)       -- preferred method

```

## See also

* Math
* `bor()`
* `bxor()`
* `bnot()`
* `lshr()`
* `shl()`
* `shr()`
* `rotl()`
* `rotr()`
The Three Finns World

The Three Finns World is a pangea planet (which it was Earth), that is made by this deity of the Three Finns Universe Which it was made 9000 aeons before the

Crossuniverse events happened. The former inhabitants of this planet are The Three Finns, and Yoko Littner.

## Native Species of the world

After it's creation, the 5 races of Humans were created The list of the species are shown

* Penwardians (Adventure Time Humans), they are located in Europe
* Normals (Real Life Humans), they are located in Africa as it was their original continent
* Comicans (Comic Book Humans), They are located in North America
* Animens (Anime Humans), they are located in Asia
* Disneylings (Disney Humans), they are located in South America
Shrinko8

Shrinko8 is a command-line tool written in python that operate on pico-8 carts and supports:

* Aggressive minification to save on character count & compressed size.
* Linting - reporting of common code issues
* Converting p8 to png (and vice versa), with resulting compressed size being a bit smaller than Pico-8
* More (e.g. token counting, running custom python scripts to process carts)

It can be found in GitHub here:

* https://github.com/thisismypassport/shrinko8
Ceil

ceil( num )
Returns the nearest integer at or above a number (its "ceiling").
num

The number.

*return-value*

The nearest integer at or above num.
If the given number is a fractional value between two integers, the higher integer is returned.

If the given number is already exactly an integer, it is returned as-is.

## Examples

```
print(ceil(5.9))   -- 6

print(ceil(-5.2))  -- -5

print(ceil(7))     -- 7

print(ceil(-7))    -- -7

```

## See also

* `flr()`

* Math
Info

info
Prints information about the cartridge currently loaded in memory.
You execute this system command from the PICO-8 command prompt.

The command prints the current size of the source code relative to the code size limits, including the character count, the Lua token count, and the compressed byte count. If the code exceeds any of these limits, you will not be able to run the cart or save it in the `.p8.png` file format.

This command also prints the last known filename for the current cartridge, if any. This is the filename used when running the `save` command without arguments, and used for detecting changes automatically when using an external editor.

## Examples

```
> info
file: gta6.p8.png
tokens:       604 /  8192
chars:       5322 / 65535
compressed:  2657 / 15616

```

## See also

* `save`
* `load`
Felix the Cat

Felix the Cat is a sneaky feline who, previously, lived in his own universe, until he was dragged to the Crossuniverse. There, he made his home in the Lovecraftian World and resides there, along with his buddy Roscoe. He is well-known for carrying around a magic bag of tricks which can transform into virtually anything. Despite this, his most useful tool is his tail. He can transform his tail into anything, from a sword to even a screaming flashlight (seriously).

## Appearance

Felix is a feline, but stands on two legs like a human. He has big eyes, a big head and black fur. Actually, the fur is so black, he can, sometimes, turn into a strange black fluid to bypass certain situations. He is not very tall.

## Personality

He is mischievous, but has a big heart and is kind. He has some problems in dealing with women and often becomes depressed upon rejection. Some of his rejections got him so low that he was unable to acquire any kind of job. This is why he is often jobless.

He is also lazy towards doing certain chores, such as ironing and cooking. Because of this, he asks his magic bag of tricks "kindly" to do his chores.

## Powers

He has some abnormal features and can, sometimes, even break the laws of physics. He stated that all this craziness happens because he is "a cartoon character", revealing that he is very aware of his non-existant condition. He can use his magic bag of tricks, his tail and a exclamation/question mark which appears on the top of his head to create different stuff. They can even emulate the proprieties of metal. He once transformed his tail into a sword and his magic bag into a rocket, revealing that their proprieties may be more complex than they look.

He is also known to, sometimes, transform into a strange black fluid in order to bypass certain situatons. The fluid can also stick to anything and allows Felix to camouflage himself. He once camouflaged himself on a cow after being chased by a bunch of aliens.

## Story

After being sent to the Crossuniverse, Felix the Cat begun wandering the cold streets of the Lovecraftian World in search for a job, but eventually gave up and became a beggar. The profession gave him some bucks, since he was a cute kitty. He was eventuall adopted by an asian couple and taken to Japan. The couple taught Felix how to hunt down whales using harpoons. Upon being stopped by Popeye, the couple sent Felix the Cat back to Europe.

Felix the Cat was eventually hired by a cartoon making company and became a super-star. He begun having adventures along with his roommate, Roscoe. Since then, Felix gained a lot of money and became rich.
Mid

mid( first, second, third )
Returns the middle of three numbers. Also useful for clamping.
first

The first number.

second

The second number.

third

The third number.

This function is designed simply to give you the middle value out of three.

However, one of its best uses is frequently overlooked: it can clamp a value to a range.

If you call `mid(min_val,val_to_clamp,max_val)`, it acts exactly like the similarly-formatted `clamp()` function in other languages. The result will be `min_val` if val is too low, `max_val` if val is too high, and `val` itself if it is in range.

## Examples

```
print(mid(8, 2, 4))           -- 4

print(mid(-3.5, -3.4, -3.6))  -- -3.5

print(mid(6, 6, 8))           -- 6

-- clamp to 0..1
print(mid(0, v, 1))

-- sort three values
v0 = min(min(a,b),c)
v1 = mid(a,b,c)
v2 = max(max(a,b),c)

```

## See also

* Math
* `max()`
* `min()`
Rawequal

rawequal( tbl1, tbl2 )
Compare two tables, bypassing metamethods
tbl1

A table to compare.

tbl2

Another table to compare.

When creating things like custom containers and objects, one often overrides the `__eq` metamethod with custom code, possibly to to do deep comparisons or to omit certain elements, but might then need to check for regular equality without going through that override. This can be done with `rawequal()`.

## See also

* `setmetatable()`
* `getmetatable()`
* `rawset()`
* `rawget()`
* `rawlen()`
* **`rawequal()`**
* Metatables
* Tables
* Lua
Rotr

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.

rotr( num, bits )
Rotates the bits of a number to the right.
num

The number.

bits

The number of bits to rotate.

The `rotr()` function takes a number and a bit count, and returns the result of rotating the bits of the number to the right 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 two's complement representation for negative and positive values. Bit rotating uses the entire number representation. (See examples below.)

See `rotl()` to rotate bits to the left.

## Superseded by >>< operator

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

## Examples

```
-- 64 = 0b01000000 binary
-- 8 = 0b00001000 binary
print(rotr(64, 3))     -- 8

-- 1.000 = 0b0001.0000 binary
-- 0.125 = 0b0000.0010 binary
print(rotr(1, 3))      -- 0.125

-- -4096.0000 = 0b1111000000000000.0000000000000000 binary (two's complement)
-- rotate --> by 12 bits
-- 15.0000 = 0b0000000000001111.0000000000000000 binary (two's complement)
print(rotr(-4096,12))  -- 15

-- (when printing fractional numbers, pico-8 rounds the decimal
-- representation to four decimal places. the largest fractional
-- portion is about 0.9999847... in decimal, so pico-8 prints it
-- as "1".)
-- approx 1 = 0b0000000000000000.1111111111111111 binary (two's complement)
-- -15.9998 = 0b1111111111110000.0000000000001111 binary (two's complement)
print(rotr(0b0.1111111111111111, 12)  -- -15.9998

print(64 >>< 3)        -- 8, preferred method

```

## See also

* Math
* `band()`
* `bor()`
* `bxor()`
* `bnot()`
* `shl()`
* `shr()`
* `lshr()`
* `rotl()`
Land Gruber

Creator
 Genre
 Player Count

## Description

From one of the final scenes of the Die Hard movie, Hans Gruber is about to fall to his death. Help him catch as many coins and bank notes as possible before he goes splat!

## Rules

* As Gruber falls, batches of coins and bank notes are falling from the Nakatomi Plaza, which must be collected.
* Avoid flames, as they deduct points.
* Bank notes are worth the most while coins are worth the least during Gruber’s fall. Hitting Theo’s limo at the end has the largest bonus.
* The cloud layer indicates the player is at the halfway point of their fall/the game, along with a flashing indicator signaling that the ground/limo is near.

## Controls

* At the title screen, press z or x to start the game.
* Use the arrow keys to move Gruber (left/right only).
* Use the enter or p key to pause the game or reset the cart.
* Use the x key to confirm game configuration at the menu and to skip cutscenes.
* Use the z key to change the rating from R to PG-13 at the menu.
Minima

Creator
 Genre
 Player Count

## Description

In Minima you take on the role of a hero trying to save the land of Miskatonia from the evil Faxon and its minions. It's up to you to explore the land, talk with the people, figure a few things out, and get strong enough to defeat the Faxon and its legions of orcs, undead, and daemons.

Minima is an homage to the 8-bit Ultima games (especially Ultima II, Ultima III, Ultima IV, and Ultima V) as they were on the Commodore 128. Like those games, it features a 2D world view and 2D town views as well as 3D dungeon views.

### Minima Command Keys

a  attack
c  cast spell

d  dialog, talk, buy

e  enter, board, mount, climb, descend

p  pause, bring up game menu

f  fountain drink; force chest; flame torch

s  sit & wait

w  wearing & wielding

x  examine, look (repeat to search)

### PocketC.H.I.P. Command Keys (if not changed)

/  attack
0  cast spell

left shift  dialog

z  enter, board, mount, climb, descend

enter  pause, bring up game menu

fn  fountain drink; force chest; flame torch

tab  sit & wait

right ctrl  wearing & wielding

-  examine
Clip

clip( x, y, w, h, [clip\_previous] )
Sets the clipping region in the draw state.
x

The x coordinate of the upper left corner of the clipping rectangle.

y

The y coordinate of the upper left corner of the clipping rectangle.

w

The width of the clipping rectangle, in pixels.

h

The height of the clipping rectangle, in pixels.

clip\_previous

If true, the new clipping rectangle is formed by clipping it to the area of the one currently specified within the draw state.

*return-value*

An x,y,w,h tuple representing the previous clipping rectangle.
When the draw state has a clipping rectangle set, all drawing operations will not affect any pixels in the graphics buffer outside of this rectangle. This is useful for reserving parts of the screen. An optional boolean argument allows multiple clipping rectangles to be easily combined in an AND fashion, handy for rendering stacks.

When called without arguments, the function resets the clipping region to be the entire screen and returns the previous state as 4 return values `x, y, w, h` (since PICO-8 0.2.0d).

## Technical notes

The actual current GPU clipping rectangle is memory-mapped and may be read or written directly with `peek()` and `poke()`:

* 0x5f20 / 24352: x\_begin (no pixels < x\_begin will be drawn)
* 0x5f21 / 24353: y\_begin (no pixels < y\_begin will be drawn)
* 0x5f22 / 24354: x\_end (no pixels >= x\_end will be drawn)
* 0x5f23 / 24355: y\_end (no pixels >= y\_end will be drawn)

**Important:** These values are not in the same format as the arguments to `clip()`. See the draw state documentation for details.

## Examples

```
-- set the clipping region to exclude 8 pixels at the top and bottom
clip(0, 8, 128, 112)

-- these circles are clipped to (0-127,8-119)
circfill(10, 10, 8, 8)
circfill(10, 118, 8, 8)

-- reset the clipping region to full screen
clip()

-- these circles are not clipped
circfill(40, 10, 8, 7)
circfill(40, 118, 8, 7)

-- get the current clip rectangle from its memory-mapped addresses
clip\_x=peek(0x5f20)
clip\_y=peek(0x5f21)
clip\_w=peek(0x5f22)-clip\_x
clip\_h=peek(0x5f23)-clip\_y

```

## See also

* Graphics
* Draw state
* `camera()`
* `color()`
* `cursor()`
* `pal()`
* `palt()`
Splore

splore
Activates the cartridge explorer.
Splore is a graphical interface for exploring PICO-8 cartridges. You can use Splore to browse, search, and play cartridges published to the forum (BBS) directly over the Internet. You can also use Splore to navigate the cartridge storage area, with or without an Internet connection.

To activate Splore, run the `splore` command (or its abbreviation, `s`) from the PICO-8 command prompt.

Select a cartridge to run it. To return to Splore from the running cart, press the `Esc` key to pause the cart and display the pause menu, then select Splore.

To return to the command prompt, press `Esc` from within the Splore interface.

## Saving carts locally

When you select a published cartridge, PICO-8 downloads the cart, loads it into memory, and runs it. The cart is stored on your computer in a cache separate from the cartridge storage area.

To save the cart to the storage area:

1. While the cart is running, press `Esc` to pause the cart.
2. Select **Splore** to return to the browse interface.
3. Press `Esc` again to exit Splore and return to the command prompt.
4. Use the `save` command to save the cart.

As usual, you can press `Esc` from the prompt to examine the contents of the cart.

## Examples

```
> splore

> s

```
Set draw slice

set\_draw\_slice( slice, [vertical] )
Set the target voxel plane for PICO-8 draw code running inside of Voxatron.
slice

The target slice, normally 0..63, but 0..127 if `vertical` is true.

vertical

Option to render vertically into X,Z slices instead of X,Y slices.

When running PICO-8 draw code in Voxatron, this function may be used to set the Z value at which PICO-8 pixels should be drawn as voxels. It may be called more than once per frame to produce 3-dimensional shapes and effects.

If `vertical` is set to `true`, this function instead sets the Y value that PICO-8 pixels should be drawn into a vertical X,Z slice. Note however that, because Voxatron's volume is 128x128x64, these slices will only be 128x64, rather than the usual 128x128 of X,Y slices.

## Attention

This function is *only* documented in Voxatron, and it is *only* used when PICO-8 code is running inside of Voxatron. It serves no purpose when running inside of PICO-8 and does *not* normally need to be called.

## Examples

```
-- in voxatron, draw an 8x8x8 rainbow cube slice-by-slice in z,
-- left of the middle of the visible 128x128x64 volume
for i=8,15 do
  set\_draw\_slice(28+i)
  rectfill(54, 60, 61, 67, i)
end

-- now draw another 8x8x8 rainbow cube slice-by-slice in y,
-- to the right of the first cube
for i=8,15 do
  set\_draw\_slice(60+i, true)
  rectfill(66, 28, 73, 35, i)
end

```
Update buttons

\_update\_buttons( )
Update the gamepad state.
This internal, undocumented function is how the PICO-8 application updates the gamepad state.

While the user's code is first being run, the gamepad state is expected to be undefined and unreliable, as calls to functions like `btn()` or `btnp()` are only expected to be done inside of `_update()` and possibly `_draw()`, which will not occur until after all of the user's code has been run through.

If, however, the user wishes to do some processing of inputs over an extended period of time before control returns to the outer loop that calls update/draw, they may force updates to the gamepad state by calling `_update_buttons()`. Typically, one would call this between a call to flip() and the logic that depends on the buttons.

## Warning

As an undocumented function, `_update_buttons()` 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

```
print("press any button to continue")
repeat
  flip()
  \_update\_buttons()
until btn() != 0

```
Magic Jewelry: The Tale of 1000 Gems

Creator
 Genre
 Player Count

## Description

The player must move and place puzzle pieces however they best see fit in order to score as high as possible and keep the game going for as long as possible.

## Rules

* Puzzle pieces drop down from the top towards the bottom of the screen. They are comprised of one to three colors; the player must arrange them so the same color makes a straight line that is at least three pieces of the same color together. This will make rows of the same puzzle pieces disappear.
* The next upcoming piece (i. e. not the one currently in play) is displayed at the top right area of the screen.
* If puzzle pieces stack up to the top of the screen without being disposed of then the game will end.
* At various intervals, a piece will appear that is beige and its pieces comprise the letter X. Placing this anywhere on the puzzle pieces in the playing area will cause several of them to be removed. This also indicates that the next level has been reached.

## Controls

* Use the X key to start a new game.
* Use the left/right arrow keys to move the current piece in play.
* Use the X or Z keys to change up the order of the current piece in play.
* Use the down arrow key to pull the current puzzle piece down to the bottom of the screen.
* Use the Enter or P key to pause the game.
Add

add( table, value, [index] )
Adds a element to the end of a sequence in a table.
table

The table.

value

The value to add.

index

The index for the value to be inserted.

*return-value*

The value that was passed in.
The `add()` function adds an element to a sequence in a table.

If an index is not supplied, it is assumed to be `#table+1` and the value is appended to the end of the table.

The `add()` function returns the object being added. You can ignore this return value if you don't need it.

A stack can be easily emulated by using `add(s,v)` to push and `v=deli(s)` to pop.

## Examples

```
t = {1, 5}
add(t, 7)  -- t = {1, 5, 7}
add(t, 9)  -- t = {1, 5, 7, 9}
add(t, 3, 2)  -- t = {1, 3, 5, 7, 9}

-- used to create and keep track of all players
players = {}
function new\_player(pad\_index, name)
  return add(players, {pad\_index, name})
end

```

## See also

* Lua
* Tables
* `all()`
* `del()`
* `deli()`
* `foreach()`
* `pairs()`
* `ipairs()`
Line

line( [x0,] [y0,] [x1,] [y1,] [color] )
Draws a line between two points.
x0

The x coordinate of the start of the line. If omitted, the x coordinate of the end of the previous line is used, or 0 if no previous line has been drawn.

y0

The y coordinate of the start of the line. If omitted, the y coordinate of the end of the previous line is used, or 0 if no previous line has been drawn.

x1

The x coordinate of the end of the line.

y1

The y coordinate of the end of the line.

color

The color of the line. If omitted, the color from the draw state is used. This also sets the color in the draw state.

The `line()` function is very versatile, with different operations depending on how many arguments are supplied. Line segments, strips, and loops are all easily created with this function.

This is how PICO-8 interprets each possible set of arguments:

* `line(x0, y0, x1, y1, color)` - Draws a line from (x0, y0) to (x1, y1) in the given color. Remembers (x1, y1) as the current endpoint and color as the current pen color.

* `line(x0, y0, x1, y1)` - Draws a line from (x0, y0) to (x1, y1) in the current pen color. Remembers (x1, y1) as the current endpoint.

* `line(x1, y1, color)` - Draws a line from the current endpoint to (x1, y1) in the given color. If there is no current endpoint, nothing is drawn. Remembers (x1, y1) as the current endpoint and color as the current pen color.

* `line(x1, y1)` - Draws a line from the current endpoint to (x1, y1) in the current pen color. If there is no current endpoint, nothing is drawn. Remembers (x1, y1) as the current endpoint.

* `line(color)` - Invalidates the current endpoint. Remembers color as the current pen color.

* `line()` - Invalidates the current endpoint.

## Examples

```
-- draw 20 white lines in random locations
color(7)
for x=1,20 do
  line(rnd(128), rnd(128), rnd(128), rnd(128))
end

-- draw a red diamond shape using separate line segments
line(63, 0, 126, 63, 8)  -- this first line sets color to 8/red
line(126, 63, 63, 126)   -- no need to set color again
line(63, 126, 0, 63)
line(0, 63, 63, 0)

-- draw the same red diamond shape using line continuation
line(63, 0, 126, 63, 8)
line(63, 126)
line(0, 63)
line(63, 0)

-- draw a regular n-gon using line continuation
function ngon(x, y, r, n, color)
  line(color)            -- invalidate current endpoint, set color
  for i=0,n do
    local angle = i/n
    line(x + r\*cos(angle), y + r\*sin(angle))
  end
end
ngon(64, 64, 50, 8, 12)  -- a blue octagon

```

20 white lines in random locationsA red diamond shapeA blue octagon
## See also

* Graphics
* Draw state
* `tline()`
* `circ()`
* `circfill()`
* `rect()`
* `rectfill()`
Pico-Man

Creator
 Genre
 Player Count

## Description

It's Pac-Man, you should know what to do! Clear out mazes of dots and avoid the pursuing monsters for the most part.

## Rules

* The player controls Pico-Man, who must clear out mazes of dots by eating them. Pico-Man moves slightly faster when the corridors are dot-free. Eating all dots in a maze leads to the next more difficult level. Bonus prizes appear up to two times during a level below the monster pen if Pico-Man can eat them before they disappear.
* Four monsters start pursuing Pico-Man throughout a level; if one of them catches him they will lose a life and the game will end when there are no more remaining lives. An escape tunnel located on the center sides of the maze will slow down a pursuing monster, however, along with one of four energizers in the corners of each maze will temporarily make the monsters vulnerable to the point where Pico-Man can eat them. Once they start flashing, however, they are about to turn back into their dangerous state.

## Controls

* Use the X or Z keys to start a game.
* Use the arrow keys to control Pico-Man.
* Use the Escape or Enter keys to pause the game.
Shoot Stuff!

Creator
 Genre
 Player Count

## Description

The pollen wars are in full effect and it's up to you to destroy the robots that seek to eradicate all pollen from your planet.

## Rules

* The player's character can either jump over or shoot robots.
* Robots come in three variations: a fast-moving small blue robot, a slow-moving small red robot that fires projectiles upwards and a large red robot that moves slowly but takes five hits to be destroyed. All robots have an indicator as to how many hits they will take before being destroyed (one to two for small robots and five for the large ones). At top center of the screen is a tally as to how many robots need to be destroyed in order to win the game (with a count total of 100 is required).
* Along with robots, fireballs also start falling from the sky, which, if they hit the ground they will explode and cause damage to the player if they're too close to it. Coming into contact with robots and the red robots' projectiles will take off a health unit (as indicated at top right) and the game will end when the player runs out of health.
* The player starts off a game with 20 rounds of ammunition; occasionally a destroyed robot will leave behind extra ammo. Crates fall down from the sky which will restore health if they land without being shot and the player picks them up, or they can be used to totally refill the player's ammo level to maximum (20 rounds) if the crate lands and the player shoots it. However, if the crate lands on a robot it will be destroyed and a bonus health unit or ammo will be lost. If the player runs out of ammo the game will end.

## Controls

* Use the x + c keys to start a new game.
* Use the x key to shoot.
* Use the left/right arrow keys to move.
* Use the up arrow key to jump.
* Use the p or Enter key to pause the game.
Super Mega Bread

Creator
 Genre
 Player Count

## Description

The player takes the role of Bread Man, who has the ability to throw butter or jump in mid-air using butter. There are four levels, each with a different theme and gimmick. The main antagonist is Dr. Yogurt, who is polluting BreadLand with processed junk food.

## Controls

* Z: Jump
* X: Throw Butter
* Left/Right: Move
* Up/Down: Aim Butter
* Enter: Pause/Settings

## Unlockables

* Level Select: Beat the game once.
* Mayo Mode: Go into the crevice in the ice block at the start of Grape Glacier.
	+ You start each level with limited Mayo, with no pickups or checkpoints.
* Yogurt Mode: Stand in the corner right above the exit to the final boss room.
	+ You play as Dr. Yogurt and have shorter jumps.

## Links

* https://jclermont.itch.io/super-mega-bread
Menuitem

menuitem( index, [label,] [callback] )
Adds a custom item to the PICO-8 menu.
index

The item index, a number between 1 and 5.

label

The label text of the menu item to add or change.

callback

A Lua function to call when the user selects this menu item.

To remove a previously added item, call `menuitem(i)` where `i` is the index of the item to remove.

*New in PICO-8 0.2.0.*

If the callback returns true, the pause menu remains open.

Menu items can detect Left and Right button presses. The callback takes a single parameter that is a bitfield of Left (0) and Right (1).

It can also detect O (4), X (5) and Pause (6), but it cannot distinguish them (if any is pressed, the parameter is the bitmask sum = 16+32+64 = 112).

Combining all these properties allows a developer to add a numeric field tuner (decrease on Left, increase on Right, and possibly reset on X).

By making the callback function immediately return anything on either a Left or Right press, the field tuning feature can be disabled.

## Examples

```
menuitem(1, "restart puzzle", function() reset\_puzzle() sfx(10) end)

function display\_hints()
  hint\_shown = level\_id
end
menuitem(2, "show hints", display\_hints)

-- v0.2.0
menuitem(3, "foo", function(b) if (b&1 > 0) then printh("left was pressed") end end)

```

```
function my\_menu\_item(b)
    if(b&1 > 0) menuitem(\_,"left!")
    if(b&2 > 0) menuitem(\_,"right!")
    if(b&32 > 0) menuitem(\_,"selected!")
    return true -- stay open
end

menuitem(1, "select me", my\_menu\_item)

```
PocketChip

PocketCHIP (or "PocketC.H.I.P.") is a handheld computer produced by Next Thing Co. It is based on the CHIP platform, and includes a 480 x 272 LED backlit touchscreen and a membrane keyboard. The removable CHIP computer provides a 1 Ghz ARMv7 processor, 512 MB of RAM, wireless Internet, Bluetooth, one USB port, one headphone/video jack (a TRRS jack). PocketCHIP is powered by a 5-hour rechargeable battery.

PocketCHIP includes a full version of PICO-8 preinstalled, tailored to the hardware to support using the touchscreen with the built-in editing tools (as a substitute for the mouse). You can use the wireless Internet connection with Splore to browse and play published carts.

PocketCHIP (and CHIP) run the CHIP Operating System, which is based on Debian Linux. The CHIP includes GPIO (general purpose input/output) pins for building hardware extensions, and the PocketCHIP case extends these pins to through-hole pads along the top of the unit.

PocketCHIP retails for $69 USD. As of June 2016, it is available for pre-order at the special price of $49 USD, shipping in July. The CHIP computer sells separately as a development platform for $9.

CHIP and PocketCHIP originated as a Kickstarter campaign.

* PocketCHIP website: https://getchip.com/pages/pocketchip
* CHIP technical documentation: http://docs.getchip.com/chip.html
Clockwork

Clockwork is a trollpasta who once defeats The Three Finns with her Mary-Sue powers (such as dodging the bullets and blades). She appeared in the Crossuniverse for no reason. She later died in her second battle with The Three Finns (which is also her last battle).

## Personality

It appears that she is afraid of the Gurren Lagann (The robot from the Anime) because of it's size. She may be sadistic because she killed her entire family and the guards.

## Combat

During combat, she is hard to defeat (unless your riding the giant robot) because she may dodge bullets and avoid getting stabbed. What ever she sees the Gurren Lagann, she stops in fear, making the rider of the Gurren Lagann step on her like an example of her second and last battle with the Three Finns which she gets stomped to death by the Finn Lagann (Like the Gurren Lagann with it's head replaced with Finn's head).
P8Coder

P8Coder is a third-party development tool for Windows for making games for the PICO-8 platform. It includes a code editing environment that lets you organize the code for a cartridge in multiple tabs, as well as a sprite sheet viewer. P8Coder was created and is maintained by movAX13h.

* Link: http://blog.thrill-project.com/p8coder-pico-8-programming-tool/
* Discussion: http://www.lexaloffle.com/bbs/?tid=3351
Pico8

PICO-8 (or "Pico-8") is a *fantasy console* by Lexaloffle Games for making, sharing, and playing small computer games and programs.

PICO-8 is available for purchase as an app for Windows, Mac OS X, Linux (Intel), and Raspberry Pi. It also came bundled with the PocketC.H.I.P. portable computer. See the PICO-8 website for purchasing information.

PICO-8 intends to capture the fun and creativity of writing programs for the small personal computers of the 1980's, without the hassles of an arcane platform. The specifications are purposefully limited so that making games is easy and fun. The console has built-in tools for creating graphics, sound, music, and code, all of which run within the console's 128-by-128 pixel screen. You program PICO-8 using the Lua programming language.

Games are saved as *cartridges* (or "carts"), which are just small files that can be shared over the Internet. You can publish a cartridge to the PICO-8 forum, where anyone can play it directly in a web browser without the PICO-8 app, discuss it, and download it to examine it in the app's tools. Publishing a cart also makes it accessible from within the app's Splore cartridge explorer.

You can also export cartridges with a standalone player that can be embedded into any web page, suitable for commercial publication on game networks such as itch.io.

PICO-8 has an active developer community, with hundreds of games, tools, and resources for learning how to make games.

## Specifications

* Display
	+ 128 x 128 pixel resolution
	+ 16 colors
* Sound
	+ 4 channels
	+ 8 waveforms
* Controls
	+ two 6-button controllers (up, down, left, right, x, o) available from a PC keyboard
	+ connect up to eight 6-button controllers via SDL
* Cartridge size
	+ 32 kilobytes per cartridge
	+ 128 x 128 pixel sprite sheet
	+ 128 x 32 tile map
	+ 64 sound patterns, 64 music patterns
	+ Lua code space limited by characters and tokens
* Memory
	+ addressable memory regions for graphics, sound, and general use
	+ separate RAM for the Lua call stack
	+ 64 values (256 bytes) persistent memory per cart
	+ Raspberry Pi GPIO pins mapped to memory

## See also

* PlayingGames
* GettingStarted
Oval

oval( x0, y0, x1, y1, [col] )
Draws an empty oval shape.
x0

The x coordinate of the upper left corner.

y0

The y coordinate of the upper left corner.

x1

The x coordinate of the lower right corner.

y1

The y coordinate of the lower right corner.

col

The color of the oval's border. If omitted, the color from the draw state is used.

## Examples

```
-- draw a red oval border of a wider shape
cls(0)
function \_draw()
  oval(10,30,100,100,8)
end

```

## See also

* Graphics
* Draw state
* `ovalfill()`
* `circ()`
* `circfill()`
Pset

pset( x, y, [c] )
Sets a pixel in the graphics buffer.
x

The x coordinate.

y

The y coordinate.

c

The color value. If not specified, uses the current color of the draw state.

The `pset()` function sets a pixel in the graphics buffer.

This operation is affected by the draw state.

## Examples

```
pset(10, 10, 7)                 -- sets (10, 10) to white
print(pget(10, 10), 0, 96, 7)   -- prints 7

pset(10, 10, 8)                 -- sets (10, 10) to red
print(pget(10, 10), 0, 104, 7)  -- prints 8

```

Repeatedly fill the screen with randomly colored pixels:

```
function \_update()
  -- \_update() is required for game loop
end

function \_draw()
  for x=0,127 do
    for y=0,127 do
      pset(x, y, rnd(16))
    end
  end
end

```

## See also

* Graphics
* Draw state
* `mget()`
* `mset()`
* `pget()`
* `sget()`
* `sset()`
Rawlen

rawlen( tbl )
Get the length of a table, bypassing metamethods
tbl

The table whose length to retrieve.

When creating things like custom containers, one often overrides the `__len` metamethod with custom code, but might then need to check the true length of the underlying table without going through that override. This can be done with `rawlen()`.

## See also

* `setmetatable()`
* `getmetatable()`
* `rawset()`
* `rawget()`
* **`rawlen()`**
* `rawequal()`
* Metatables
* Tables
* Lua