arnaught [Lexaloffle Blog Feed]

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

prt

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.

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.

Printing Special Characters

Tue, 26 Mar 2024 04:32:04 UTC

I figured out how to get the Pico8 special characters (the ones you get when typing capitals) in Picotron. The special characters start at U+0080 and go all the way up to U+0099. All unknown characters seem to display the same.

I don't know of a convenient way to type these into picotron, but if you copy paste the list below, you can save them to a text file for reference. It's a little annoying because none of them are actually printable characters. UTF-8 doesn't seem to like having them bare, so when you copy paste, it will actually be U+00C2 U+0080 instead of just U+0080.

A: 
B: 
C: 
D: 
E: 
F: 
G: 
H: 
I: 
J: 
K: 
L: 
M: 
N: 
O: 
P: 
Q: 
R: 
S: 
T: 	
U: 
V: 
W: 
X: 
Y: 
Z: 
Unknown: Â

Magic 8 Ball

Sun, 24 Mar 2024 15:03:28 UTC

magic8ball

by arnaught

[Click to Play]

This Picotron cartridge can predict the future! Simply ask it any yes or no question, shake the window, and you'll get your answer!

(I hear you can also press z to get an answer, but that seems less fun than shaking the window.)

This was a fun little project to make. I finally figured out how to edit the cartridge's metadata! (Though I'm still not sure how to do it on a fullscreen cartridge).

I wanted to put a sound effect when shaking the window, but I have no idea how to work the instrument editor lol.

Startup Folder

Fri, 22 Mar 2024 18:14:23 UTC

Some linux distros include code in the default .bashrc that chain loads files from ~/.bashrc.d. This is useful for keeping your config organized. (I like keeping my aliases in a separate file, for instance.)

I've made a snippet that does this for Picotron. Add this to your /appdata/system/startup.lua, and it will chain load any .lua files in the folder /appdata/system/startup.

startup_folder = "/appdata/system/startup"
if fstat(startup_folder) == "folder" then
	for file in all(ls(startup_folder)) do
		filename = startup_folder .. "/" .. file
		if fstat(filename) == "file" and file:find("%.lua$") then
			create_process(filename)
		end
	end
end

Pipes

Tue, 19 Mar 2024 14:17:47 UTC

Pipes 1.0

by arnaught

[Click to Play]

I made a pipes screensaver, inspired by the classic 3D Pipes Screensaver.

A pipe of a random color is created on the somewhere on the edge of the screen. It will expand outwards from its starting point, choosing to go straight, left, or right. The pipe will stop when it goes out of bounds, and a new pipe will be created.

I am not saving information about the pipes manually. I just draw the current pipe, and never cls. All the old pipes stay on screen and the new ones are drawn above. Previously, I saved all of the pipe connections and colors in a 30*17*6 table which was redrawn every frame, but then I realized that I could get rid of that by just removing cls. So instead of storing and drawing up to 3060 sprites every frame, instead I only store and draw one.

I only have 3 pipe sprites for each color: a vertical pipe, a horizontal pipe, and a bend pipe. The bend pipe is flipped based on what direction it needs to be. There is a visual bug when flipping a pipe vertically on the bottom row (y = 256) that causes it to become misaligned with the rest. I think it's a bug with the sprite flipping so there's no way I can fix it. (Well, there is a way I can fix it, and it's called quadruple the number of bend sprites. But I'm not doing that.)

(Edit: The sprite flipping issue was fixed in 0.1.0c!)

The pipe only expands once every 8 frames. I think at full speed it goes too fast to watch it.