Exporting

Overview

This guide is sourced from the Picotron Manual

This goes over the different formats for exports alongside how to export cartridges.

Exporting a PNG

To save a copy of the currently loaded cartridge in .p64.png format (without making it the new working cartridge), press ctrl-7 while running the cartridge to capture a label and then:

> export foo.p64.png

Cartridges in .p64.png format can have up to 256k of (compressed) rom data, and can be shared on the Lexaloffle BBS.

Exporting in HTML (a web export)

Cartridges can be exported and shared as stand-alone html pages.

To export the currently loaded cartridge as a single file:

> export foo.html

View the page by opening the folder and double clicking on it:

> folder

HTML Export Size Limit

The html exporter can handle carts that are up to 8MB in .p64.rom format (use info command to check).

Beyond that size, fetch() can be used to download more data as needed using stat(151) to prepend the host and path the page is being served from: fetch(stat(151).."level2.pod").

Exporting Binary Executables

Binaries for Windows, Mac and Linux can be generated by exporting to a .bin folder:

> export foo.bin

A folder for each platform is generated for testing, along with zip files that are ready to distribute. It is recommended to distribute the zip files as-is instead of re-packing them, because they include file attribute bits that are set on the executable files when unzipped. For example, it is possible to export from a Windows dev machine, and then a linux user can unzip and run the cart without needing to chmod +x thegame.

Icons

The cartridge's 16x16 icon is used as the host file and window icon if one exists. Colour 0 is always taken to be transparent, and every other colour index is solid.

Extra Files

Bundle files in the .zip output with -e:

> cart -e readme.txt foo.bin

When a folder is given instead of a file, the contents of that folder are flattened and saved in the root of the zip.

To remove the metadata section of a text file so that it looks nicer outside of Picotron:

> store_metadata("foo.txt",{metadata_format="none"})

Storing Data from a Binary Export

store() data somewhere in "/appdata/mygame" as usual, and it will be persisted on the end user's machine. Exports use a separate home data folder on host so that they don't accidentally interfere with any regular Picotron installations. Instead of a home path (in linux) of:

~/.lexaloffle/Picotron

Exports by default all use:

~/.lexaloffle/Picotron/exp/shared

This means that exports can still read and write each other's /desktop, settings and other files. That is usually not a problem (and is sometimes desirable), but if additional separation is needed, add export_home to the cart's metadata:

> store_metadata("/ram/cart", {export_home = "my_game_name"}) 

The exported cartridge will then have its own isolated home path, and can do things like mess up /desktop with low risk of interfering with other exports:

~/.lexaloffle/Picotron/exp/my_game_name

By using export_home, and bundling .p64.rom files inside the exported cartridge, it is possible to create software that uses the Picotron desktop environment. For example, suites of tools that boot up into their own customised desktop environments, or UI story games that come with a desktop already populated with files and widgets.

Binary Export Size Limit

The binary exporter can handle carts that are up to 32MB in .p64.rom format (use info command to check). After exporting, additional data can also be stored in a folder called "data" in the same path as the executable. When this path exists, it is automatically mounted as /host_data on boot.

Note that the data/ folder is not automatically bundled into the distributable zip files, so for exports that need > 32MB of data, some extra work is needed to create distributables.

Native Window Exports

Binary exports can run as a native window directly on the host desktop by using the -n switch:

> export -n foo.bin

Or set export_native_window to true in the cartridge metadata before exporting:

> store_metadata("/ram/cart", {export_native_window=true})

This allows the cartridge's window and the host window to be one and the same thing. There is no boot sequence, desktop, pause menu or message bar. When the program is finished, the host window immediately closes. Only a single userland process (4) can run in such an export, so features like open() and chooser() are also not available.

Runtime errors also cause the window to close immediately, but the error is still logged to {picotron home}/exp/shared/log.txt.

The virtual window resolution can be any size within Picotron limits, but may not change during runtime. The host window is resizeable and fullscreenable (alt+enter) as usual. Settings like stretch, pixel_perfect and pixel_scale are applied when storing changes to /appdata/system/settings.pod. Other window attributes like .frameless, .moveable and transparency are ignored by the host window.

If no window is created by the exported cartridge, it will continue to run headless and all print() commands go to stdout (if there is one). The usual file system mounting rules apply though, so along with the startup time, it is not very useful for creating general commandline tools.

Cartridge Exporter Limitations

1. Exported cartridges can not load and run other cartridges that were not part of the export.

The exporters are targetted at authors wishing to export and distribute their own work, and this limitation aims to reduce unwanted exploitation of the Picotron ecosystem.

It is still possible to bundle many .p64.rom cartridges together inside an export and run them with create_process(); just make sure you have permission from all of the included cartridges' authors first.

1. When exporting fullscreen cartridges, the user can not access the Picotron desktop, terminal, or other parts of the system. To enable escaping the fullscreen workspace using alt+L/R or Ctrl-P: create the window with can_escape_fullscreen set to true:

window{can_escape_fullscreen = true}

1. bbs:// can not be used from exported cartridges.

2. widgets, themes, screensavers and wallpapers are not loaded on boot, and are not selectable in the settings app from exported cartridges. This is to avoid exports that use the same default exp/shared/ data from interfering with each other, including producing runtime version vs. cart version mismatches. Instead, a cart can optionally customise its own desktop each time it is run.