Picotron FAQ
// Picotron is still in early development! Answers here are subject to change, but mostly true.
What is Picotron?
Picotron is a Fantasy Workstation for making pixelart games, animations, music, demos and other curiosities. It has a toy operating system designed to be a cosy creative space, but runs on top of Windows, MacOS or Linux. Programs made with Picotron can be exported as stand-alone binaries or Web apps, or shared directly with other Picotron users in a special 256k png cartridge format.
What is Picotron Playground?
Picotron Playground is a web-based, minimal version of Picotron used to test the api and runtime during early development. It is janky, subject to undocumented changes, has no permanent storage, and includes only a provisional code editor and terminal program. But it does provide a reasonably complete runtime environment and can be used to try out some of the newer / weirder picotron features. Sometime in 2023 a general alpha will be available as a downloadable binaries (following a similar model to PICO-8), at which point Playground may or may not continue to exist.
How does Picotron Differ from PICO-8?
Although Picotron is conceptually similar to PICO-8 -- an imaginary machine that you can make things for with built-in tools -- it aims to be a more practical and flexible development environment. The two main differences are in specifications (larger display and cartridge capacity), and the way that built-in tools are implemented.
Unlike PICO-8 and Voxatron, all of the design tools in Picotron are written in Lua and are editable from inside the machine itself. For example, it is possible to add a custom brush to the pixel editor, or to create new tools from scratch that run in fullscreen workspaces alongside the bundled editors. There is also a desktop-like workspace for making smaller tools that suit windowed / tiled layouts. Tools that run in windows or commandline can be distributed as .p64.zip files, or exported as stand-alone applications.
These additions and the subsequent shift in focus of the machine give Picotron the title of 'Workstation' rather than 'Console'. Instead of 'Plug in a keyboard to get a devkit!' It feels more like: 'Unplug the keyboard to get a console!'
Will Picotron be Compatible with PICO-8?
Yes and no. Picotron supports PICO-8 style shorthand syntax, almost the whole API, and other compatibility features that make it relatively easy to port PICO-8 cartridges. However, it is not designed to run PICO-8 carts out of the box, because the underlying machinery is quite different. For example, Picotron uses floating point numbers, and so can only approximate PICO-8's fixed point math behaviour.
Can I Use Picotron to Make Large Games?
Yes! Programs exported as stand-alone binaries/html do not have a size limit and can also optionally read loose files included with the export.
Cartridges saved in .p64.png format however are limited to 256k of (compressed) data. This format is intended for posting cartridges on the Lexaloffle BBS, and targets small and medium sized projects. Picotron compresses sprite and map data automatically, so 256k can still mean quite a substantial project, depending on the type of game and art style.
How is Memory Mapped in Picotron?
As well as usual Lua objects, Picotron includes a general purpose userdata api that can be used as 1d~2d arrays of several types (u8, i16, i32, f64). All of Picotron's standard resources are stored in this way (bitmaps, audio data, maps), and can be accessed with the same API functions. This allows for more efficient storage and manipulation of things like large in-memory world data than is available by using standard Lua data structures.
a = userdata("u8", 16, 16) -- allocate a 16x16 block of memory
set(a, 4, 3, 15) -- set a value at 4,3
spr(a, 50, 50) -- 2d arrays can be treated as sprites
Integer arrays can be mapped to Picotron's ram in 4k increments, making their contents addressable with PICO-8 style memory functions and the @ operator:
a = userdata("u8", 8192) -- an 8k 1d array
memmap(a, 0x20000) -- map it to 0x20000..0x21fff
poke(0x20123, 42) -- set a value in the mapped region
assert(@0x20123 == get(a, 0x123))
More about Userdata:
picotron_userdata.html
How is Cartridge Data Stored?
Graphics, maps, audio data and source code are bundled into a single cartridge file (.p64, .p64.png), and like PICO-8 it is usual to have many .p64 files lying around. Although they are single files on the host machine, they can also be treated as folders from inside Picotron. So it is possible, for example, to copy resources directly across cartridges using the cp utility:
cp mycart.p64/gfx/foo.gfx mycart2.p64/gfx
The current working project is system-wide and stored in a special location: /ram/cproj. /ram is a ram disk and all contents will be lost when picotron is closed (note that is true for the entire disk in the web-based Picotron Playground version). The load and save commandline utilities simply copy the current working cartridge to and from that location.
Resources can be manually loaded and manipulated as userdata however the author sees fit, but the API and runtime rules also provide optional low-friction workflows. For example, the spr() function can take either a u8 userdata object or a sprite index as the first argument. When a numeric sprite index is given, the high bits refer to a sprite bank (0..63, in bits 0x3f00) and the low bits (0xff) indicate the sprite in that bank. Graphics files named gfx/{integer}.. are automatically loaded into that sprite bank on boot. Each file can be an array of sprites, or a png file that is automatically colour-fitted and diced into 16x16 sprites. Maps are 2d userdata of type i16 that use the same indexing scheme (and can be passed as the first parameter to tline3d).
All files in Picotron are "pods", which are strings encoding structured Picotron Object Data: picotron_pod.html
How Fast is the CPU?
It depends how you measure it. In terms of raw Lua instructions, Picotron is only around 2x the speed of PICO-8 (so, around the same per scanline). The gfx api is much faster though (around 8x per pixel), and more api primitives are provided to carry a lot of general heavy work. For example, although Picotron isn't intended for making 3D games in particular, but a reasonable 3D engine could be constructed using tline3d() (perspective correct scanline rendering), sort() for back-to-front painting ordering, and userdata to store and manipulate matricies. The Picotron CPU limits have been chosen to allow any Picotron cartridge to run on relatively low-spec machines and web browsers.
How does the Palette Work?
Picotron has a 6-bit display, so 64 colours can be displayed at any one time. The palette can be defined with arbitrary RGB values; there are no hard-wired colours like PICO-8. There is a default system palette of 32 colours, with 32 empty slots, that is a combination of the standard PICO-8 palette and 16 extra colours. The extra colours are not the secret PICO-8 palette, but are intended to function nicely when recombined with the standard 16. Additional colours can also be displayed in the same frame by defining up to 3 alternative palettes and switching between them per scanline.
WIP default palette (32 colours):
Picotron's draw state includes a 4k colour table: a 2d 64x64 lookup table is observed by all Picotron gfx functions. Every time a pixel is drawn,
the value written to video memory is determined by looking up the table using 2 indexes: the colour of the target pixel, and the draw colour.
Internally it looks like this:
putpixel(x, y, coltab[getpixel(x,y)][draw_color])
There is no concept of a "draw palette" in Picotron; instead functions like pal() and palt() modify the colour table to produce the
equivalent behaviour. In addition to performing sprite recolouring and transparency, the colour table can be set up to implement
effects like efficient shadow rendering, fog and additive blending.
Provisional documentation on Picotron's GFX Pipeline:
picotron_gfx_pipeline.html
Which Platforms will Picotron Support?
Initially Picotron will target Windows, Mac, Linux, Raspberry Pi (3 and higher) and HTML5/wasm. Longer term, Picotron's runtime will be made available as a permissively licensed C library that depends only on a small amount of OS-specific code, and uses SDL2 to implement this by default. This will allow any cartridges exported from Picotron (and Picotron itself) to run on any available third-party ports of the runtime.
When will Picotron be Available?
A limited alpha version is available here, and a more general version will be available for purchase sometime in 2023 (with editing tools and at least an html cartridge exporter). I'm still focusing mostly on Voxatron and PICO-8 in the meantime, but will be making incremental changes to Picotron Playground to give all 3 machines a chance to co-evolve. You can also try #picotron on twitter for sporadic previews and developments.
