--[[pod_format="raw",created="2024-03-10 12:02:52",icon=userdata("u8",16,16,"00000101010101010101010101000000000106060606060606060606060100000107010606060606060606060606010000010106060707070707070606060100000106060607070707070707060601000107010606060606060706070606010000010106060707070607070706060100000106060607060706060606060601000107010606070707070707070606010000010106060607070707070706060100000106060606060606060606060601000107010606060606060606060601010000010101010101010101010101070100000101070707070707070707070601000000010606060606060606060601000000000001010101010101010101000000"),modified="2024-03-25 20:51:12",revision=64,stored="2024-03-10 12:03:12"]]
-==================================================-
Getting Started with Picotron
-==================================================-
--[[pod_type="image"]]unpod("b64:bHo0AF4HAACACwAA8RlweHUAQyDwZATw-----9Zd8FaN8A2N8DyNUI3wTQ0QDRANAA3wDQ0ACwAh8DwHABKQDQADHwAj-Q8dAII6-QzwNC3wBC0AI-0PPQA3Og0ANgCTAA3wMh0gHfACFgBF0B3ADSkAwfAKDfAwHWAd8AANYBoAEWAWAKgEHTAN8C8NoA3gFwBRQA0QDTAGAJ4gDfAXLdD9C3AfADBQDQAfAJ4WDSANwB3wBx0jABIdfgBgIA3wD-0DLwBf8AUNAA1LAABTAB0ADQAqAJ8d4B1QDRD9BRApAAEiMC0lAIANAA3ADQANUBwBIAMNKwBxUA3gHdANUCsAEp1MAAEpADEQzRAnAD3AHTAoAABTAEFNIA0wKABSDTAtMA0sADFgDTD7AAwwACSNYCwAMyBNICwANRANgCwAYEAN8AAd4AcAETrVAEAQPQAdAQFwMA2wHQAd0CgANB0AHToAXkANYB0wOACBrRAdAA1ADaBcABnAbAAt8AMvAKnwCg2QHQAtAB2wwgAAOwEREAgAYDAN8AAt8IQAAi4AImAtrgARoLYAJCANXAAAagAvAB0yAAEAHgABoQFBHQAtgFYAADkBAjYAQTAdQA0aAAA6ABFdOAASXTYAEUAUABMghgAEhgFtID0wDQBtZgAAFwEGAgAxIA1AUwAA1wARAI8BBe4BARcCSF3wAR1oABQ9ZwIYYDwCITANJwACYQAAGAEGAgATIBAAMABNIJACCZwCC10BEiCGAFJNAC3wEuUCCyEAAlAAERCEAErwEv0LIQAM2QAFSgEQPVcAL-A0TgAEAzoBL-AzTQAKAZwAEz1RAAAtAKBQDbBdwA1QLfA4TAAB5AAVPUoA8gNQDcANME1wDSAtID3wNP0MQB3YAAGHAGBQDdAdYC13AWOQHfBUDRBVASHwNQADgIANMB3QHfBSzQLwJy0ATfAKrfARDVD9BHA98AIN8FKdAA3wCw2gDfAQDVD9BmANEB0wPYAN8EgdcA0ADUAt8AoNwDYDALMA8ALwBT0gDQBtMD1QHfBGHXAtQDoAkOAN8A4dED3wAR0CsA0APTA9MF3wSB2gwQP4AQsN8AEN8CQdgC0AHYAd8FAWAOAjDcA9oA3wPK1gLQAdYCQBEAkjA9jwIB2QnZAd8DjtQB0QGACwHw1ALRAdMB0wHRB5AGA3PRAtED0kABBQYwSACA1AjUAN8B4hASAdQIQDwB0gLSAN8DYtIC0gLS4BEmAnADAwDYBVAlEdTTAdQCsAaDBN8DQ9gCMAESCLA3AgDfAlDTBNTQHVMA3wOw0AHTAtMB0wXSUAANoD8QIgDfAkDSCNIF0gDfA5LUBNQJ4CBWsAIBBN9wRA8CNNEKwCUT0QTfA4aQAHJwCQBU0wjTBN8CZd9gRKAF3wPUYAsgI9EC3gLRA98CJNFwVAAF3wO98ARC1ADTAlAABtA1AgLcAtIA8CAPcAACkAUCBd8DFtigQTQCcA4dAdMC0gLaAtIC0wHfAePgDyAwAN8Db9LWAdYC0g7SAtYB3wIRUA8wQ1DfAtDUANkC0wrTAtkA3wIQ0gLACRQA2wPeA9sA3wZQAxLfA03gMCAgAArgOB0E2gTdAN8BzPAEkQHfAyIABgIA3wAf0B-gETGQQBMvAxDc0ACAQAADcEgPAEzfAEDfAXfwRZDUAd8C9JAO8ADfAnDfAUHZBNQA3wLhsAAHATDUAtMA0AmAHwAS0NAP0pAB3wKQ3wEQ0gnRCHARIsJwACFgBAEE0gPZwAQQAd8DMsAGEN8CsN8BatBhIAfwMCnQEyIB0ACgARPRcAIgkNKgAxFR0gpwMWACoAAtUDAeEDoj2grSAd8C0N8BnMAx41IwAABAhBHXANMCcAEBi8AQYnABUgJQAyAB2Q4gQQL7cHAGYGL-A2TAACNYC9MCUAAMQALvA2TABijSANkA0gJwAB5gYfAE4ABCM9MKIIIPAxUgAB0AINnACAHQANID0QvSAUAQOPA0-wFg0w7wAGQD0QzVAsAD5gDVAsAAlYAPABjRA9ID0gDcANsA1ADVANoI0EWhH9A-AwVwABCgCAEA1gHSBNIE0IAgD1AhGwLQABbQQeMIYAQe0gXTAzAgArCQArAEmQHfAFLQCwIB0A-QwgjbBNoA0PBIKQTbANgD3wBH4A0v0C8AnN8AE98Agt8AEMCFEd8AD9AdECIPAA3gDAoA3wBR0Q-QAQHfAEcAlxXQAd8AEN4PQCIP0DfQCMMN3wB-0E8AYeAACHAAB8AhGgwAGAwA3wCP0A8AdLB2KN8ALt8DIiAAFCAAkeADN98AMeABACEgdy0A3wCG0AfRwAMG3wBCwABB4AYAPdMA3wBxEBuW3wBg1wDQBtII1wIQABXgAg8AZBAEEFDYCN2AcRDSMA8BEx-TDwBP0A8AP9CUANAP0R8FHtcB1wTUD9APABHcB9ILAD0YtdAB0gHTD9AKBd4H1OBfAGk-0X8AV9QC3wlW0g-QLwxw2QDfDUBQAS0woA8ABATfDWDSAN8Nwt8P---0c=")
Congratulations on being the new owner of your very
own Picotron Fantasy Workstation!
This is a quick guide to get you started using
Picotron and creating your own cartridges.
** Workspaces **
Press ALT+LEFT or ALT+RIGHT to cycle through desktop
workspaces. Click and drag the toolbar to reveal a
tooltray.
On boot, /appdata/system/startup.lua is run if it
exists, and you can use that to install widgets in
the tooltray. See /system/startup.lua for an example.
** Customizing your Desktop **
You can open the system settings via the Picotron
menu (top left) or by typing settings at the prompt.
To create your own lists of themes, wallpapers and
screensavers, create the following folders:
/appdata/system/themes
/appdata/system/wallpapers
/appdata/system/screensavers
** Creating a Program **
Picotron always has a global cartridge sitting in RAM
at /ram/cart ready to be edited. Click on the code
workspace (it looks like "()" at the top right) and
type in a program:
function _draw()
cls(1)
for i=1,24 do
circ(240,135, i*t(), i)
end
end
Now hit CTRL-R to run it. You can do this from
anywhere -- CTRL-R means: "run whatever is in
/ram/cart", and the entry point for any cart is
always main.lua.
To stop a running program, press ESC and then ESC
once more to return to the last desktop workspace.
To create a windowed program, the window size can
be set with: window(width, height), or to run at
different resolution use the vid() function:
vid(0) 480x270
vid(3) 240x135
vid(4) 160x90
Some handy functions to get started:
cls(col) -- clear the screen to a colour (0..63)
circfill(x,y,radius,col) -- filled circle
line(x0,y0,x1,y1,col) -- draw a line
spr(index,x,y) -- draw a sprite
map() -- draw the default map
sfx(index) -- play a sfx
music(index) -- play a pattern
Picotron programs can define a function called _draw
that is called each frame, _update that is always
called at 60fps, and _init that is called once when
the program is run.
** Saving a Cartridge **
From terminal, use the save command:
/>save mycart
An extension will automatically be added (.p64) and
the contents of /ram/cart will be stored in that
cartridge. Inside Picotron, cartridges are folders, so
you can open them up and look inside! But in the real
world they are stored as single .p64 or p64.png files.
** Commands **
Some handy commands:
ls list the current directory (folder)
cd change directory (e.g. cd /desktop)
mkdir create a folder
folder open the current folder in your Host OS
open open a file with an associated editor
To create your own commands, put .p64 or .lua files
in /appdata/system/util.
** Running a Cartridge **
There are some demos in /system/demos:
> cd /system/demos
/system/demos> load carpet.p64
Cartridges are also like regular applications that can
be opened by double clicking on them, or typing their
name from the command prompt. If the cartridge
creates a new fullscreen workspace, you can close it
by pressing ESC and then right-clicking on the
workspace icon.
** GFX Editor **
The second workspace is a sprite editor. Each .gfx
file contains up to 256 sprites, and if the filename
starts with a number, it can be indexed by the map
editor.
Don't forget to save your cartridge after drawing
something -- the default filenames all point to
/ram/cart and isn't actually stored to disk until
you use the save command (or CTRL-S to save the
current cartridge)
s select
space pan
f/v flip selection horizontall or vertically
cursors move selection
ctrl-c copy selection
ctrl-v paste to current sprite
ctrl-b paste big (2x2)
tab toggle RH pane
-,+ navigate sprites
ctrl modify some draw tools (fill)
rmb pick up colour
Draw sprites from your program with spr(index, x, y).
0.gfx is loaded automatically.
** MAP Editor **
Changes made to /ram/cart/gfx/0.gfx automatically
show up in the map editor.
The map editor uses similar shortcuts, with a few
changes in meaning. For example, f and v also flip
selected tiles, but also set special bits on those
tiles to indicate that the tile itself should also
be drawn flipped. The map() command also observes
those bits.
** SFX Editor **
There are 3 modes to the SFX editor: an instrument
(synth patch) designer, SFX editor (for playing
sequences of notes) and a pattern editor, for
arranging SFXs into groups to play music.
Each instrument is a tree of nodes that can either
create or modify an audio signal. Please refer to the
PFX6416 design document for details:
https://www.lexaloffle.com/dl/docs/picotron_synth.html
Basic node instrument editing:
Click and drag a knob to turn it
Right mouse draw to adjust the range of a knob
Click and drag an envelope to a knob field
-> The envelope now applies to that range
Press SPACE while in the instrument editor to
kill all sound.
** Saving a PNG Cartridge **
To create a .p64.png ready to be uploaded to the
BBS, first capture a label while running it (ctrl-7)
and then save it with a .p64.png filename extension.
To print a title and author/version on the label,
type: about mycart.p64.png
** Loading a BBS Cartridge **
> load #cart_id
This loads the cart with a temporary filename in
/ram. Don't forget to save somewhere to disk if
you want to keep any changes.
** Reading Games Controllers **
Use btn(index) to read the state of game controllers:
0,1,2,3 Stick L,R,U,D
4,5 Buttons: O, X
6,7 (reserved)
8,9,10,11 Secondary Stick
12,13,14,15 Buttons, SL, SR
A secondary stick is not guaranteed on all platforms!
It is preferable to offer an alternative control
scheme that does not require it, if possible.
Keyboard controls are currently hard-coded:
0~5 Cursors, Z/X
8~11 ADWS
12,13 F,G
14,15 Q,E
--------------
There are still many unfinished and rough corners
but I hope you enjoy messing around with this first
version. See you on the BBS!
-- zep
