arnaught [Lexaloffle Blog Feed]

Orbit XS

Fri, 15 Aug 2025 13:41:37 UTC

An Orbt XL demake in Pico-8 for LowRezJam2025!

How To Play

The planet is orbiting a black hole! Press any button (Up, Down, Left, Right, Z/O, or X/X) to move the planet away.

Points are awarded based on how close to the black hole you are. (3 points/second for the inner ring, 2 points/second for the middle ring, and 1 point/second for the outer ring.)

Asteroids are also being pulled in, too, so try not to get hit. Near misses award bonus points! Green asteroids change the direction of the orbit once they hit the black hole.

Asteroids will spawn faster for each minute you're alive.

Additional planets can be unlocked with points. This is just cosmetic. Try and earn 400 points to unlock all the planets! (And try and beat my high score, which is 577!)

Bubbles

Fri, 11 Jul 2025 13:54:24 UTC

zxbubbles

by arnaught

[Click to Play]

My attempt at recreating the bubbles demo from this youtube video (the bubbles part starts at around 15 minutes)

Circles are drawn at a random position on the bottom row, and the screen is scrolled (by using blit to copy the display onto itself offset by -1 rows).

It's not quite the 31 bytes the one in the video is, but I tried to keep it small. 152 bytes minified, 141 minified+compressed.

HTTP Server

Wed, 09 Jul 2025 16:29:45 UTC

HTTP Server

by arnaught

[Click to Play]

An HTTP Server in Picotron!

Running the cart will start a demo, hosting a server on localhost:8000. The cart will display the access logs. The site serves a form. Once submitted, the form results will be displayed in the log.

Full instructions on GitHub: https://github.com/Rayquaza01/picotron-http

livesplit

Mon, 07 Jul 2025 15:55:41 UTC

livesplit

by arnaught

[Click to Play]

A Proof of Concept livesplit client for Picotron!

Requires Livesplit (livesplit.org) with the TCP server running.

Usage: Z to start/split, X to reset

Color matches the Livesplit colors (green for running, blue for stopped, grey for not running)

When the TCP server is not connected, the timer will be red. Once it connects, it will change to normal.

Image Viewer

Sun, 02 Mar 2025 00:30:09 UTC

Image Viewer

by arnaught

[Click to Play]

This is a cart to view png or qoi images in Picotron. It uses @pancelor's import png library. It's basically a different frontend for import png.

You can zoom in/out an image with scroll wheel, and pan across the image by dragging.

You can copy the image as a sprite to clipboard by pressing Ctrl+C.

You can open png and qoi images (as well as pal and hex pallets) by dropping them on the window (or, default_app png /path/to/imgviewer.p64 to set image viewer as the default app for pngs).

The statusbar shows the size, viewport position (coordinate of top left pixel), zoom, and loading progress.

The image used in the label preview is Cat demonstrating static cling with styrofoam peanuts from Wikipedia.

Original image: Sean McGrath from Saint John, NB, Canada, Derived image: Black Rainbow 999, CC BY 2.0 <https://creativecommons.org/licenses/by/2.0>;, via Wikimedia Commons

Calendar Widget

Sat, 01 Mar 2025 14:50:04 UTC

Calendar Widget v1.1.0

by arnaught

[Click to Play]

A simple calendar widget. Install to tooltray with drag-and-drop.

Displays the current month's calendar, and highlights the current day.

Click the block (top left) to toggle the window's transparency. (When started on the tooltray, it will automatically be transparent)

The date is calculated in local time by default. Switch to UTC by clicking the house (local) indicator.

Using my DateToUnix function: https://www.lexaloffle.com/bbs/?tid=146596 (Hey, I finally found a use for it!)

Changelog

v1.0.1 (2025-03-01):

Fix text centering

v1.0.2 (2025-03-09):

Fixed day of week being wrong after daylight savings starts

v1.1.0 (2025-05-13):

Settings override file (/appdata/bbs/calendarwidget/settings.lua) to change colors, format, and week start

Analog Clock Widget

Sat, 01 Mar 2025 14:44:10 UTC

Analog Clock Widget 1.0.0

by arnaught

[Click to Play]

A simple analog clock widget. Install to tooltray with drag-and-drop.

Time is 12 hour by default. Switch to 24 hour by clicking the digital display, or the am/pm indicator.

Time is local time by default. Switch to UTC by clicking the house (local) indicator.

Right click to close widget on desktop.

Bouncy Ball

Sat, 22 Feb 2025 22:07:11 UTC

Bouncy Ball v1.0.2

by arnaught

[Click to Play]

A bouncy ball for your Picotron desktop!

Open the cart and a ball will drop on your desktop! Pick it up, and throw it around. It will bounce and roll on your open windows!

When you're done with the ball, right click it to close it.

Using rspr by @fletch_pico to get the ball rolling (literally!) - https://www.lexaloffle.com/bbs/?tid=141706

If you spawn multiple balls, they won't interact with each other. I have the window background set to be transparent (using poke(0x547d, 0xff)), but this seems to cause the window to be excluded from /ram/shared/windows.pod.

Video Showcase: https://www.youtube.com/watch?v=x22LJ8qvKN4

Inline (one-off) Image Editor

Thu, 20 Feb 2025 13:20:20 UTC

inlineimg

by arnaught

[Click to Play]

You can print inline images (one off characters) using an escape code (\^:<character>). For example, \^:447cb67c3e7f0106 will print a cat.

The format is 8 bytes in hexadecimal representing a row, and each bit representing a column, for a 8x8 monochrome image. However, writing it out by hand is obviously a pain. I found some editors for Pico8 (https://www.lexaloffle.com/bbs/?tid=50298), but I couldn't find one for Picotron. So I made one.

There is a 8x8 grid of tiles, representing the image. Clicking a tile inverts it. The escape code and character preview are shown at the bottom of the window.

Ctrl+V to paste an image from clipboard and load it into the editor
Ctrl+C to copy the image in hexadecimal format
Ctrl+B to copy the image in binary format.

The binary escape code is supposed to be more compact. However, it contains unprintable characters, so it needs to be escaped if you want to put it in your code. Once escaped, it's often less compact than the hexadecimal escape code.

https://pico-8.fandom.com/wiki/P8SCII_Control_Codes#Drawing_one-off_characters

Balloon Run (Pico 1k Jam 2024)

Wed, 19 Feb 2025 13:42:53 UTC

balloonrun

by arnaught

[Click to Play]

I made this as my submission for Pico 1k Jam 2024, but I never actually posted it on the BBS.

Move with Left+Right, Jump with Z (O). Try and dodge the parachuting enemies. See how long you can last!

Additional Links:

Balloon Run on Itch (contains the compressed 1021 byte version) - https://rayquaza01.itch.io/balloon-run
Source code gist - https://gist.github.com/Rayquaza01/802ccea3ac1ce22a9a812d17f84e6bd6

Working with Dates

Fri, 17 Jan 2025 05:23:07 UTC

The date() function returns a formatted date.

It takes three arguments

format, the format to use for display (See: Programming in Lua 22.1 - Date and Time). Starting the format with ! makes it UTC, otherwise it will be local time.
t, the timestamp either as a string (in the default UTC YYYY-mm-dd HH:MM:SS) or Unix timestamp (seconds since 1970-01-01 00:00:00)
delta, an amount of seconds to add to the timestamp.

date() gets the current time in UTC, and is used to generate timestamps in Picotron (for modified and created times).

date("%Y-%m-%d %H:%M:%S", timestamp) converts timestamp to local time. (So you can store timestamps in UTC and later display them in local time)

date(nil, nil, -86400 * 10) subtracts 10 days from the current time.

Since timestamps are in YYYY-mm-dd HH:MM:SS format, they can be compared directly as strings.

Example: "2025-01-17 05:00:00" < "2025-01-17 05:10:00" returns true, as the first timestamp is smaller than the second timestamp (by 10 minutes).

I did not realize timestamps could be compared as strings until after writing a function to parse timestamps into Unix timestamps lol.

Here is the function to do that. It takes a timestamp string (from date), and returns the Unix timestamp. You can convert a Unix timestamp back into a string using date. Not sure if there are many practical uses for this, since you can do most things with date directly, but I'm sure it'll be useful for something.

I also made a quick function that uses the Unix timestamps to calculate the UTC offset (I don't think there's a direct way to do this using date, but I could be wrong.)

Conway's Game of Life (with PVP)

Wed, 15 Jan 2025 19:27:20 UTC

conway_pvp

by arnaught

[Click to Play]

This is a version of Conway's Game of Life with PVP support! It's inspired by/based on this DougDoug stream: A Crew VS. Z Crew in Conway's Game of Life.

The rules are very similar to regular Conway's Game of Life.

Any living cell with < 2 living neighbors dies (underpopulation)
Any living cell with 2 or 3 living neighbors lives
Any living cell with > 3 living neighbors dies (overpopulation)
Any dead cell with exactly 3 live neighbors lives (reproduction)

However, there are two colors, red and blue. For rules (2) and (4), when the cell lives, it will match the color of its adjacent cells. If there are more red adjacent cells, it will become red. If there are more blue adjacent cells, it will become blue. If there are an equal number of red and blue adjacent cells, it will randomly choose one.

The grid is 25x25, and it wraps around.

Place red cells with LMB
Place blue cells with RMB
Erase cells with MMB
Change the simulation speed with Scroll
Step the simulation with O (Z)
Run the simulation with X (X)
Reset simulation with R

https://github.com/Rayquaza01/conway-pvp

Using an External Editor - extload and extrunner

Sat, 11 Jan 2025 23:09:48 UTC

Typically, when using an external editor, I do cp -f cart.p64 src and then work on src externally. Every time I make a change, I need to load src before running. Then, I can put it back in the cart by doing cp -f src cart.p64.

The suggested way of using external editors in the docs is to have the code externally, and simply include it from inside the cart. This will automatically use the latest external change, but it makes it harder to switch back to editing inside Picotron, as you need to change parts of your code to put everything back in the cart.

I made a quick utility to make loading an external folders easier.

extload is a modified version of /system/util/load.lua that loads a folder for external editing. It saves the path of the folder in /ram/extcart.pod and loads extrunner instead of the actual folder. (It also loads the workspaces from the folder, though this is a little janky.)

extrunner is a dummy cart that cds into the external folder (from /ram/extcart.pod), loads the graphics and sfx (by including /system/lib/resources.lua), and runs it (by including main.lua).

So, to set up an external project:

Create a cart for the project (cart.p64)
Extract the cart (cp -f cart.p64 src)
Load the extracted cart (extload src)
Make any changes with an external editor, test those changes with Ctrl+R
When done, rebuild the cart (cp -f src cart.p64)

This lets you work on any cart externally without having to load src every time you make an external change and without needing to make any code changes!

extload.lua

--[[
	extload
		load an external folder
]]

cd(env().path)

local argv = env().argv
if (#argv < 1) then
	print("\f6usage: load filename -- can be file or directory")
	exit(1)
end

filename = "/appdata/system/util/extrunner"
extdir = fullpath(argv[1])

attrib = fstat(filename)
if (attrib ~= "folder") then
	-- doesn't exist or a file --> try with .p64 extension
	filename = filename..".p64"
	if (fstat(filename) ~= "folder") then
		print("could not load")
		exit(1)
	end
end

-- remove currently loaded cartridge
rm("/ram/cart")

-- create new one
local result = cp(filename, "/ram/cart")
if (result) then
	print(result)
	exit(1)
end
store("/ram/extcart.pod", extdir)

-- set current project filename

store("/ram/system/pwc.pod", fullpath(filename))

-- tell window manager to clear out all workspaces
send_message(3, {event="clear_project_workspaces"})

--meta = fetch_metadata("/ram/cart")
meta = fetch_metadata(extdir)

if (meta and type(meta.runtime) == "number" and meta.runtime > stat(5)) then
	print("** warning: this cart was created using a future version of picotron.")
	print("** some functionality might be broken or behave differently.")
	print("** please upgrade to the latest version of picotron.")
end

if (meta) dat = meta.workspaces

--[[ deleteme
	dat = fetch("/ram/cart".."/.workspaces.pod")
	if (not dat) printh("*** could not find\n")
]]

-- legacy location;  to do: deleteme
if (not dat) then
	dat = fetch("/ram/cart/_meta/workspaces.pod")
	if (dat) printh("** fixme: using legacy _meta/workspaces.pod")
end

-- legacy location;  to do: deleteme
if (not dat) then
	dat = fetch("/ram/cart/workspaces.pod")
	if (dat) printh("** fixme: found /workspaces.pod")
end

-- at the very least, open main.lua if it exists
if ((type(dat) ~= "table" or #dat == 0) and fstat("/ram/cart/main.lua")) then
	--dat = {{location="main.lua"}} -- relative to /ram/cart/
	dat = {{location=extdir.."/main.lua"}}
end

if (type(dat) == "table") then

	-- open in background (don't show in workspace)
	local edit_argv = {"-b"}

	for i=1,#dat do

		local ti = dat[i]
		local location = ti.location or ti.cproj_file -- cproj_file is dev legacy
		if (location) then
			--add(edit_argv, "/ram/cart/"..location)
			add(edit_argv, extdir.."/"..location)
		end
	end

	-- open all at once
	create_process("/system/util/open.lua",
		{
			argv = edit_argv,
			pwd = extdir
		}
	)

end

print("\f6loaded "..filename.." into /ram/cart")
print("\f6loaded external cart " .. extdir)

extrunner main.lua

https://gist.github.com/Rayquaza01/574a21a168aa38dc4c0b8b3ec2caf69b

ini Parser

Fri, 10 Jan 2025 21:31:32 UTC

I made a simple ini parsing/dumping function. load_ini() converts an ini string to a table, and dump_ini() converts a lua table to an ini string.

This could be useful for projects that have a configuration file. Using an ini might be better for user configs since ini supports comments.

The ini format is simple. Section headings are marked with [section] and items are stored as key=value. Subsections are separated with a dot. Inline comments are not supported, but comments at the start of the line are.

Strings don't have to be quoted, but you should quote them.

Example:

[heading]
a=1
b=2

[heading.sub]
c="hello"
d="world"

[heading.array]
1=4
2=5
3=6

This will convert to:

{
  heading = {
    a = 1,
    b = 2,
    sub = {
      c = "hello",
      d = "world"
    },
    array = { 4, 5, 6 }
  }
}

With the way I wrote it, it can handle anything that can be parsed with unpod(). This may be useful for writing some things (such as arrays) more compactly. The following is equivalent to the above example:

[heading]
a=1
b=2
sub={c="hello",d="world"}
array={4,5,6}

Changelog

2025-04-02:

Allow subheadings to be numbers, providing a different way of writing arrays, and fixing an inconsistency with dump/load

[array.1]
some=value
[array.2]
other=value

Code under the cut

https://gist.github.com/Rayquaza01/e2cedb3ab53d166fdcd2c1a9cc950b1e

Trash Manager

Fri, 10 Jan 2025 14:59:46 UTC

trashman v1.0.3

by arnaught

[Click to Play]

This is a trash manager for Picotron that loosely follows the XDG Trash Specification. You can use it to delete and and later restore files from trash.

Full usage instructions are in the README (also available from "Help" inside the cart), but basically you can drag/drop files to move them to trash. Left click a file in trash to restore it, right click a file in trash to permanently delete it.

You can also use Trash Manager as a CLI utility.
trash [files] to move files to trash
trash --list [search] or trash --search [search] to list/search trash
trash --restore [files]
trash --restore-all to restore all files
trash --delete [files] to permanently delete files
trash --empty or trash --delete-all to permanently delete all trash

Finally, you can use it in the tooltray. You can drop files to the indicator to move them to trash, and you left click the indicator to open the GUI or right click it to empty the trash.

Changelog

v1.0.1 (2025-02-18):

Use argv[0] instead of prog_name (0.1.1e compatibility)
Use open instead of accessing notebook.p64 directly
Support installing tooltray widget by dragging to tooltray
Ctrl+Drag to move tooltray indicator (Tip: Hold right click on the indicator to focus it first)
Move delete action in for tooltray to Middle Click (0.1.1e compatibility)
Remove gap between final item and status bar
Must be unsandboxed to work!

v1.0.2 (2025-02-18):

Fix bug where can't open cart from indicator or double click
All instances of help use open

v1.0.3 (2025-03-01):

https://github.com/Rayquaza01/trashman/releases/tag/v1.0.3
Make moving tooltray widget easier (no ctrl+drag required)

Snowglobe

Wed, 18 Dec 2024 18:41:11 UTC

Snowglobe

by arnaught

[Click to Play]

A little snowglobe application. Shake the window to make the snow fall. More shaking causes more snow to fall! (If you don't want to shake the window, you can also use the scroll wheel.)

Uses the same shaking detection as in #8ball. I drew the scene Pixelorama, and imported it using #importpng.

PUSH - Terminal Replacement

Thu, 05 Dec 2024 03:35:01 UTC

PUSH (Picotron Upgraded SHell) is a modified version of terminal.lua I made that allows you to add modifications from lua modules. You can place modules in /appdata/system/terminal/ and PUSH will load them.

Without any modules, PUSH changes very little (cd with no arguments acts as cd /), but modules let you add more functionality.

In the repo, I have a list of examples of the sort of things you can do with PUSH, including changing the prompt, adding and overriding commands, and adding shortcuts.

cd.lua is my favorite module so far, I think. It adds replaces the default cd command and adds fish-style directory history.

https://github.com/Rayquaza01/picotron-upgraded-shell

This is very WIP, so if you have any trouble or suggestions for how to improve PUSH, let me know!

Changelog

2025.10.16

Rebase to 0.2.1b terminal
Change prompt example to include sandbox indicator
Add rm to trash alias example

2025.07.10:

Rebase to 0.2.0g terminal
Custom prompts should be mindful of input()
suspend_corun_program() cleans up some variables. Resetting cmd breaks altl, so I removed that. Not sure if there are any downsides to this?
add_line() was made local. I've changed it back to global for easy access through PUSH modules

2025.2.18:

Add in changes from 0.1.1e terminal.lua
Disable barecd when pwd is in bbs:// (fstat in bbs:// seems to always return folder, even when it doesn't exist)

Picotron Remote Terminal

Tue, 05 Nov 2024 21:21:17 UTC

Picotron Remote Terminal v2.0

by arnaught

[Click to Play]

This is a tool that lets you remotely control Picotron from the host and vice-versa.

You can run commands in Picotron by running prt <COMMAND> from the host

This is useful when working with an external editor. You can load and run the updated source code from the external editor, and build/extract the cartridge.

You can also run host commands from inside of Picotron with the host command (included in the cart at /exports/appdata/system/util/host.lua). You can even use pipelines!

Full usage and installation instructions are included in the repo: https://github.com/Rayquaza01/picotron-remote-terminal

There is an issue I know about where if the cart is running for a while, it will start dropping commands seemingly at random. Not sure exactly what causes this, but restarting the cart seems to fix it.

Changelog

2025-07-08 - v2.0

Rewritten to use Picotron 0.2.0G sockets!
- Picotron server (cart, PUSH module) now listens on port 7426 (PICO)
- Host server now listens on port 7420 (PIC0)
Host server application is no longer required! All you need now is a way to write to a TCP socket (e.g. nc)
- This is much more reliable. Commands no longer seem to drop!
Host server is still needed if you want to run host commands from in Picotron
It may even be practical to use now (maybe...)

pretty_printh and ANSI codes for colored logs

Thu, 10 Oct 2024 23:05:03 UTC

This isn't a Picotron specific thing, but you can use ANSI escape codes inside printh to make your logs colorful, which can be helpful with debugging.

To set the color, typically you do \033[38;5;<COLOR>m or \033[38;2;<RED>;<GREEN>;<BLUE>m. This sets the foreground color to a color from this chart or an RGB color code (if your terminal supports truecolor).

This just works in Picotron, but you have to do \27 instead of \033. (This is the escape code for ESC, which is 27 in decimal and 033 in octal.)

However, writing ANSI codes by hand is a pain, so I wrote a function to make inserting these codes easier, using a bbcode-like syntax.

Foreground color can be set with [fg=1][/fg] or [fg=#ff0000][/fg]
Background color can be set with [bg=1][/bg] or [bg=#ff0000][/bg]
Bold can be set with [b][/b]
Italics can be set with [i][/i]
Underline can be set with [u][/u]

function pretty_printh(s)
	s = s
		:gsub("%[fg=(#?%w+)]", function (c)
			if c:find("^%d+$") then
				return string.format("\27[38;5;%sm", c)
			end

			if c:find("^#[%da-fA-F][%da-fA-F][%da-fA-F][%da-fA-F][%da-fA-F][%da-fA-F]$") then
				return string.format(
					"\27[38;2;%d;%d;%dm",
					tonum("0x" .. c:sub(2, 3)),
					tonum("0x" .. c:sub(4, 5)),
					tonum("0x" .. c:sub(6, 7))
				)
			end
		end)
		:gsub("%[/fg]", "\27[39m")	
		:gsub("%[bg=(#?%w+)]", function (c)
			if c:find("^%d+$") then
				return string.format("\27[48;5;%sm", c)
			end

			if c:find("^#[%da-fA-F][%da-fA-F][%da-fA-F][%da-fA-F][%da-fA-F][%da-fA-F]$") then
				return string.format(
					"\27[48;2;%d;%d;%dm",
					tonum("0x" .. c:sub(2, 3)),
					tonum("0x" .. c:sub(4, 5)),
					tonum("0x" .. c:sub(6, 7))
				)
			end
		end)
		:gsub("%[/bg]", "\27[49m")
		:gsub("%[u]", "\27[4m")
		:gsub("%[/u]", "\27[24m")
		:gsub("%[b]", "\27[1m")
		:gsub("%[/b]", "\27[22m")
		:gsub("%[i]", "\27[3m")
		:gsub("%[/i]", "\27[23m")

	printh(s .. "\27[0m")
end

function error(msg)
	pretty_printh("[fg=1][b][ERROR][/b][/fg]: " .. msg)
end

function warn(msg)
	pretty_printh("[fg=3][b][WARNING][/b][/fg]: " .. msg)
end

function info(msg)
	pretty_printh("[fg=4][b][INFO][/b][/fg]: " .. msg)
end

Here's the code that I used to get the example in the screenshot:

function left_pad(s, ch, len)
	while #s < len do
		s = ch .. s
	end

	return s
end

function _init()
	pretty_printh("[fg=6][b][u]Pretty Printh Demo[/u][/b][/fg]")

	for i = 0, 15, 4 do
		str = string.format(
			"[fg=%d]color %s[/fg]\t[fg=%d]color %s[/fg]\t[fg=%d]color %s[/fg]\t[fg=%d]color %s[/fg]",
			i, left_pad(tostr(i), "0", 2),
			i + 1, left_pad(tostr(i + 1), "0", 2),
			i + 2, left_pad(tostr(i + 2), "0", 2),
			i + 3, left_pad(tostr(i + 3), "0", 2)
		)

		pretty_printh(str)
	end

	error("this is an error")
	warn("this is a warning")
	info("this is informative")

	pretty_printh("this is a line with [b]bold[/b], [i]italics[/i], and [u]underlines[/u]")

	pretty_printh("[bg=#ffffff][fg=#241f31]this is a line with hex colors[/fg][/bg]")
end

Fuzzy Finder

Thu, 10 Oct 2024 15:04:05 UTC

fzf 1.1

by arnaught

[Click to Play]

I built a fuzzy finder. You can quickly search for and open files (anything supported by /system/util/open.lua, so folders, lua files, text files, pods, etc.) Additionally, it can follow .loc files to their destination before opening (which open doesn't currently support), and it can execute .p64 files instead of opening them!

The full code and documentation is available here: https://github.com/Rayquaza01/fuzzy-finder-picotron/

This uses swarn/fzy-lua (MIT License) and mergesort.lua from TheAlgorithms/Lua (MIT License)

Changelog

v1.1 - Oct 21, 2024

https://github.com/Rayquaza01/fuzzy-finder-picotron/releases/tag/v1.1
Fixed bug where blank ignore file causes nothing to appear.
- This is still the behavior in the web player, but it should work correctly on desktop Picotron.
Commented lines in the ignore file (starting with #) will be ignored.