0xcafed00d / tac08

tac08 is an an emulation of the runtime part of the Pico-8 fantasy console. It takes a .p8 (text format) pico-8 cart file and runs it as closely posible

tac08

What is tac08?

tac08 is an emulation of the runtime part of the Pico-8 fantasy console. It takes a .p8 (text format) Pico-8 cart file and runs it closely as possible to the real Pico-8 software.

What isn't tac08?

tac08 is not a replacement for Pico-8, it provides none of the content creation components of Pico-8, such as code editing, sprite and map creation and music tools. You will still require a copy of Pico-8 to make games. Also if you just want to run Pico-8 games you will have a much better experience with Pico-8 than tac08

Why was tac08 written?

tac08's target audience are developers that want to do one or more of the following:

1. To enable Pico-8 games to be run on platforms that Pico-8 itself does not run on.
2. To embed Pico-8 games within other game engines.
3. To make it possible to extend the Pico-8 api and allow games to use features not currently supported by Pico-8

tac08 was written for my own personal use (specifically for items 1 & 3 above) but I have decided to open source it as others may find it useful.

Is it a 100% emulation?

No. tac08 is still in development, however in my testing, I have found that a large number of the most popular games work correctly.

This is a list of the most significant compatibility issues:

1. Not all peek and poke addresses are implemented, notably the current draw state values
2. Only one joystick is currently supported and it cannot be configured.
3. Saving screen shots and recording gif videos are not implemented.
4. The flip() api function is not implemented. So no tweet carts and such will work. Only games that use _init, _update or _update60, _draw will work correctly.
5. Pico-8's sound synthesizer is not implemented, however you can still play sound effects (see below)
6. The music() api function is not currently implemented (but I plan to implement it).
7. There are probably more things i can add to this list and will update as needed.

How do I get sound working then?

The way sound is implemented in tac08 is not ideal, but given current my current work loads and complexity of the Pico-8 sound system I feel it is a reasonable compromise. In order to have tac08 play sound you need to export your sound effects from Pico-8 as wav files. I have found that sound effects do not export completely if they have loops within them.

Exporting the sound effects is a two stage process. First paste the following code into the Pico-8 command prompt:

for a=0x3200,0x42ff,68 do poke(a+66,0) poke(a+67,0) end cstore(0x3100,0x3100,0x1200,"audio.p8")

This will save out a cart called "audio.p8" containing only the unlooped sfx data.

Next load the audio.p8 cart and export the actual sfx as wav files:

load "audio.p8"
export "cart%d.wav"

where "cart" is the name of your original cartridge file. You need to have these wav files in the same folder as you cart. You can delete any wav files that your cart does not need.

note that if the game creates sound at runtime then it is not currently possible to play these

How do I build tac08

Windows

A Visual Studio 2017 solution is provided in the tac08\win-tac08 directory. A copy of Visual Studio 2017 Community with C++ components installed is sufficient to build tac08.

A copy of the libSDL2 header files, libraries and DLLs are included with the solution and do not need to be downloaded separately.

1. first clone tac08 from github:

git clone --recurse-submodules https://github.com/0xcafed00d/tac08.git

2. Simply open the solution file (tac08\win-tac08\win-tac08.sln) with VS2017, and select Build Solution. Binaries will be place in either the Release or Debug directories, depending on which build mode is selected.

Linux & Mac

A makefile is supplied that will build tac08 for linux systems & Mac OSX. It has been tested on Ubuntu 16.04 & 18.04, Rasbian on a Raspberry Pi 3, a Crostini hosted debian install on a chromebook, and a Mac.

Build scripts for other environments are not currently provided (because I have not written them yet :-). tac08 is written in standard c++11. The lua interpreter is a version of lua 5.2 modified to support the syntax changes Pico-8 requires, while the lua interpreter is written in C, the modifications require it to be compiled as C++. This modification was performed by Sam Hocevar https://github.com/samhocevar/z8lua

The only external dependency tac08 is the core SDL2.0 library, so it should be possible to build tac08 from the provided code for any platform that has SDL2.0 ported to it.

1. first clone tac08 from github:

git clone --recurse-submodules https://github.com/0xcafed00d/tac08.git

2. install sdl2.0 development libraries:

For Debian based Linux distributions use apt.

sudo apt install libsdl2-dev

Other distributions and the Mac will have other mechanisms for installing libraries.

You may need to modify the SDL_PATH_LIB & SDL_PATH_INC variables in the makefile if your SDL libraries are not installed in a standard location.

3. build lua interpreter:

cd tac08/src/z8lua
make a
cd ../..

4. build tac08:

make

After this you should be left with a tac08 executable with you can run with:

./tac08 mygame.p8

tac08's Issues

new code with sound fix to be released to github

Dear Sir/Madam

I would like to humbly request that the latest version with working sound is released to github.

Thank you in advance

link error

I'm having a hard time linking liblua.a during the build process.

$ make
...
g++ bin/main.o bin/hal_core.o bin/hal_palette.o bin/hal_audio.o bin/pico_core.o bin/pico_audio.o bin/pico_memory.o bin/pico_data.o bin/pico_script.o bin/pico_cart.o bin/utf8-util.o bin/utils.o bin/log.o bin/crypt.o -L/usr/lib -lSDL2 -Lsrc/z8lua -llua -o tac08
/usr/bin/ld: bin/pico_script.o: in function `dbg_hookfunc(lua_State*, lua_Debug*)':
pico_script.cpp:(.text+0xa7): undefined reference to `lua_getstack(lua_State*, int, lua_Debug*)'
...
# 100 or so additional undefined reference errors from pico_script.cpp

But I can see that those symbols exist in liblua.a

$ nm -g src/z8lua/liblua.a | c++filt | grep lua_getstack
0000000000000540 T lua_getstack(lua_State*, int, lua_Debug*)
                 U lua_getstack(lua_State*, int, lua_Debug*)
                 U lua_getstack(lua_State*, int, lua_Debug*)
                 U lua_getstack(lua_State*, int, lua_Debug*)

The linker flags are the makefile default

LUA_LIB =  -Lsrc/z8lua -llua
LDFLAGS = $(SDL_LIB) $(LUA_LIB)

I'm on x86-64 Linux, GCC 9.1.0, binutils 2.32.

Token Optimized Call to Split() Not Supported

Pico8 supports some unusual lua syntax that allows users to save on tokens. In particular, you can call split() on a string without using the parenthesis.

I have a program that throws this error when run in tac08

col=split"2,13,6,7,14,8,14,7,6,13" [time()*5\1%10+1]: ']' expected near '\'

But the same line will run correctly in Pico8. There are a few token-optimization tricks in this line, so I'm not quite sure if it's split"...." or something else, but this definitely runs correctly on Pico-8 0.2.4.

Support for extended palette

In the new versions of pico-8 there are some secret POKEs that you can do to access an alternate darker/warmer/autumny 16 color palette. You can only have 16 colors onscreen per frame but you can mix and match from both palettes as you please.

You poke the regular color palette registers in the draw state (0x5F10-0x5F1F) as normal but add 128.
You can also do this by using pal(color_to_replace,new_color+128,1)
POKEing 0x5F2E with 1 will help with testing this as it prevents the colors from resetting after the program ends.

Here's a link to the extended colors: https://lospec.com/palette-list/pico-8-secret-palette
They look pretty accurate although I haven't checked if they're exact

Invalid continuation count in leading byte crash

Compiled and run on:
macOS 11.4 (Big Sur)
MacBook Air (11-inch, Early 2015)

Crash happens at startup with most games. The only carts I got to boot were the sample games included here. This error occurs with both .p8 and .p8.png extensions.

2022-01-04 09:41:13.781 tac08[69330:1344702] ERROR:  FAIL: invalid continuation count in leading byte 

Feature Request: Microcontroller (esp32 or arm)

How difficult would it be to port this to esp32? I'd love to contribute a hardware design but I lack the C skills to pull this off in software.

Recommend using z8::fix32

Hi, I’ve seen that you implemented the API mostly with int types. You should be aware that some functions use fractional arguments, for instance w and h in spr() which let you blit partial sprites.

If you want better compatibility, I suggest using the z8::fix32 fixed-point type from z8lua (which can be cast to and back from int, float, etc.) in all API calls.

(Also if you would like to collaborate I’d be glad to share insight!)

Are there plans to release version with SFX working by default?

I've tried tac08 on Celeste and there literally zero sounds from the game. I'd like to use tac08 with full featured sound system similar to how it just works with picolove emulator.

Cant start any game(s)

Hello , I have a problem with the usage of Tac08.
I compiled it on Ubuntu 20.04 but cant run any games.

I tried several game "Images" but I always get:

For png games
ERROR: FAIL: invalid continuation count in leading byte

For p8 games
ERROR: FAIL: expected continuation byte not found