clockworkpi/GameShellDocs
1
0
Fork 0
mirror of https://github.com/clockworkpi/GameShellDocs.git synced 2025-12-13 02:08:49 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Updated for Launcher v1.24, which includes a built-in PICO-8 installer

Dan Sanderson 2019-06-08 20:19:31 -07:00
parent b36f604d17
commit 6d3148552c
1 changed files with 46 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
Running-PICO-8-on-the-GameShell.md

@ -1,165 +1,80 @@
[PICO-8](https://www.lexaloffle.com/pico-8.php) is a *fantasy console* for making, playing, and sharing small games. PICO-8 is a commercial product by Lexaloffle Games LLP. Versions are available for Windows, mac OS, Linux, and Raspberry Pi. The Raspberry Pi version runs on the GameShell, with some set-up.
**Last updated: June 2019**
Follow these instructions to get PICO-8 and install it on your GameShell. It will run in "splore" mode, which lets you browse, download, and play PICO-8 games.
PICO-8 is a fantasy console for making, playing, and sharing small games. PICO-8 is a commercial product by Lexaloffle Games LLP. Versions are available for Windows, mac OS, Linux, and Raspberry Pi. The Raspberry Pi version runs on the GameShell, with some set-up.
## Purchase a PICO-8 license and download PICO-8 for Raspberry Pi
As of Launcher v1.24, the Launcher now has a built-in PICO-8 installer to make this even easier! You will copy PICO-8 to your GameShell, then run this installer to finish set-up.
Visit [the PICO-8 website](https://www.lexaloffle.com/pico-8.php) to create an account and purchase a license.
Follow these instructions to get PICO-8 and install it on your GameShell. It will run in the _splore_ mode, which lets you browse, download, and play PICO-8 games.
Once purchased, visit [the downloads page](https://www.lexaloffle.com/games.php?page=updates) and download the Raspberry Pi version. This file has a filename similar to: `pico-8_0.1.11g_raspi.zip`
_Note:_ The current version of the GameShell has an alternate Launcher called "LauncherGo." Only the original Launcher has the PICO-8 installer. Switch back to Launcher, if necessary.
**Tip:** Your PICO-8 license includes versions for all platforms. Download the version for your desktop computer, make PICO-8 games of your own, and run them on your GameShell!
**Purchasing PICO-8**
## Transfering PICO-8 to the GameShell
Go here to purchase your copy of PICO-8 if you don't already own it:
https://www.lexaloffle.com/pico-8.php#getpico8 ($15)
Connect your GameShell to your wifi network and get its *IP address*:
Once purchased, visit the downloads page and download the Raspberry Pi version. This file has a filename similar to: `pico-8_0.1.12c_raspi.zip`
1. Turn on your GameShell.
*Tip:* Your PICO-8 license includes versions for all platforms. Download the version for your desktop computer, make PICO-8 games of your own, and run them on your GameShell!
**IMPORTANT: Renaming the file so the installer can find it**
As of Launcher v1.24, the installer is expecting PICO-8 version 0.1.11g. It works with the latest version, but for now you have to work around this expectation.
Rename the file from `pico-8_0.1.12c_raspi.zip` to `pico-8_0.1.11g_raspi.zip`. You can do this from your computer's file explorer, or from the Mac or Linux command line:
```
mv pico-8_0.1.12c_raspi.zip pico-8_0.1.11g_raspi.zip
```
**Transfering PICO-8 to the GameShell**
The Launcher's PICO-8 installer looks for the zip file in a folder (directory) with this path: `~/games/PICO-8/` (The `~` means the `cpi` user's "home" directory, containing the `games` directory where you put various game ROMs and such. The `PICO-8` directory is inside there.)
Connect your GameShell to your wifi network and get its IP address:
1. Turn on your GameShell.
2. If necessary, connect the GameShell to your wireless network: Settings, Wi-Fi.
3. In the main launcher menu, select TinyCloud. This displays the IP address of your GameShell, such as `192.168.0.49`.
You can transfer files to the GameShell using *scp*, a file transfer method based on *ssh* (Secure Shell). Some file transfer programs know how to do this, such as [Putty SCP for Windows](https://www.putty.org/), [WinSCP for Windows](https://winscp.net/eng/download.php), or [Transmit for Mac](https://panic.com/transmit/). Connect using the IP address, an account name of `cpi`, and a password of `cpi`.
You can transfer files to the GameShell using `scp`, a file transfer method based on `ssh` (Secure Shell). Some file transfer programs know how to do this, such as Putty SCP for Windows, WinSCP for Windows, or Transmit for Mac. Connect using the IP address, an account name of `cpi`, and a password of `cpi`.
On Mac and Linux (and also Windows with Putty SCP or the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)), you can use a Terminal to do this with a command-line interface and the `scp` command. To transfer PICO-8 to the GameShell using the `scp` command:
On Mac and Linux (and also Windows with Putty SCP or the Windows Subsystem for Linux), you can use a Terminal to do this with a command-line interface and the scp command. To transfer PICO-8 to the `~/games/PICO-8` directory on the GameShell using the scp command:
```
scp pico-8_0.1.11g_raspi.zip cpi@192.168.0.49:~/
scp pico-8_0.1.11g_raspi.zip cpi@192.168.0.49:~/games/PICO-8/
```
Enter the password `cpi` when prompted.
## Connecting to the GameShell's command-line interface with ssh
**Running the Launcher's PICO-8 installer**
The steps that follow require running commands directly on the GameShell. On Windows, you can do this with an SSH client such as [Putty for Windows](https://www.putty.org/). On Mac and Linux, open a Terminal window and use the `ssh` command. Connect to the IP address with a username of `cpi` and a password of `cpi`, as above.
On your GameShell, use the Launcher to navigate to the PICO-8 icon, then select it.
To connect with the `ssh` command:
If this displays instructions to copy PICO-8 to `~/games/PICO-8`, then it didn't find the file. Review the instructions above, and make sure the file is named `pico-8_0.1.11g_raspi.zip` even if you downloaded a newer version.
```
ssh cpi@192.168.0.49
```
If this displays the "MD5 error," then **it's working!** It is displaying this error because it expected to find PICO-8 version 0.1.11g, but you provided the newer version. Tell it to continue anyway.
Enter the password `cpi` when prompted.
**Welcome to PICO-8!**
**Tip:** My GameShell responds poorly over an SSH shell connection like this. Things I type don't appear right away. It's frustrating, but if you can get through these next few steps, you won't need it again.
After it installs, PICO-8 starts in _splore_ mode. From now on, the PICO-8 option in the Launcher will just launch PICO-8 like this.
## Installing WiringPi
Move right to find the "Featured" section. If necessary, press B on [update] to load the list. Move up and down to find a game, then press B to start it.
PICO-8 requires [WiringPi](http://wiringpi.com/) to run. It uses this for features that access the GPIO pins on a Raspberry Pi. You probably won't use this feature with GameShell, but PICO-8 won't start without it.
At the GameShell Linux command prompt, run these commands:
```
git clone git://git.drogon.net/wiringPi
cd wiringPi
./build
cd
```
## Installing PICO-8
Also at the GameShell command prompt, run this command:
```
unzip pico-8_0.1.11g_raspi.zip
```
## Adding PICO-8 to the Launcher
You will start PICO-8 using a new icon in the Clockwork Pi Launcher interface. To add this icon, run this long command at the GameShell command prompt. (I recommend copy-and-pasting this into your terminal window.)
```
echo >~/apps/launcher/Menu/GameShell/PICO-8.sh SDL_VIDEODRIVER=x11 DISPLAY=:0 /home/cpi/pico-8/pico8_dyn -splore -draw_rect 32,0,256,240
```
Restart your GameShell. An easy way to do this is to run this command:
```
sudo reboot
```
(Your ssh connection will disconnect after running this command. This is normal.)
**Tip:** The `-draw_rect 32,0,256,240` part of this command tells PICO-8 to draw its screen stretched to fit a 256x240 region, with a left margin of 32 pixels so that the 256-wide rectangle is centered on the GameShell's 320x240 display. PICO-8's screen is a 128x128 square, so stretching it to a wide rectangle makes it a little wider than intended. You could make this exactly square with `-draw_rect 40,0,240,240`, but to fit these dimensions PICO-8 has to make every other pixel an odd size. I think 256x240 looks better, but you can experiment to find something you like.
## Start PICO-8 for the first time
When GameShell has finished booting and you see the Launcher again, a "PICO-8" icon (a circle with a "Pi" in it) will be in the menu. Select it.
**One of two things will happen:**
* PICO-8 starts with a chime sound, and it appears in a small square. You can use the cursor keys, but you can't use the ABXY buttons yet.
* If this happens, press MENU, then press START to select "shutdown pico-8".
* PICO-8 starts with a chime sound, but you only see the GameShell "Loading" screen.
* If this happens, connect to the command prompt via SSH and run this command:
```
killall pico8_dyn
```
When PICO-8 shuts down (using either method), it creates its configuration file and some other things. We can edit this file to fix the remaining problems.
## Configuring PICO-8
Re-connect to GameShell via SSH to get a command prompt. Run this command to open a file editor with the PICO-8 configuration file:
```
pico ~/.lexaloffle/pico-8/config.txt
```
"Pico" is a simple text file editor available on most Linux systems, including GameShell. It has nothing to do with PICO-8, it's just called "Pico" by coincidence.
Use the cursor keys to scroll down to the line that says `fullscreen_method`. Edit this value to `0`:
```
fullscreen_method 0
```
Scroll down further to the line that says `button_keys`. Edit this value as follows:
```
button_keys 0 0 0 0 13 14 0 0 0 0 0 0 0
```
Press Control-O to save the file. Press Control-X to exit Pico.
## Optional: Change the Launcher icon
The Launcher icon for PICO-8 works just fine with the default icon (the letters "Pi" in a circle). You can change this to the PICO-8 logo, if you like.
In your browser, download this image file by right-clicking and selecting "Save Image As..." (or the equivalent feature in your browser):
[[https://discourse-cdn-sjc2.com/standard17/uploads/clockworkpi/original/1X/a415c7739328fb740739c177e68c8c34d4692061.png|alt=PICO-8 icon]]
Copy this file to your GameShell using `scp` or whatever file transfer program you used earlier.
You want this file to be named `PICO-8.png`, and to be located in the folder `/home/cpi/apps/launcher/skin/default/Menu/GameShell`. You can either find this location using your file transfer program, or you can transfer the image file to the home directory (`/home/cpi/`) then move it into place with a shell command. Connect via `ssh`, then:
```
mv PICO-8.png ~/apps/launcher/skin/default/Menu/GameShell
```
Restart your GameShell (`sudo reboot`). When the GameShell is finished restarting, the Launcher should have the new icon.
## Welcome to PICO-8!
Launch PICO-8 from the Launcher. It should start reliably and at a comfortable size.
Move right to find the "Featured" section. If necessary, press B on `[update]` to load the list. Move up and down to find a game, then press B to start it.
PICO-8 games use one or both of the A and B buttons. Some games will refer to these as Z and X, or C and V, because these are the default keys on a desktop computer. Games may also refer to them as `(O)` and `(X)`, which are their "fantasy console" button icons.
PICO-8 games use one or both of the A and B buttons. Some games will refer to these as Z and X, or C and V, because these are the default keys on a desktop computer. Games may also refer to them as (O) and (X), which are their "fantasy console" button icons.
To exit a game and return to the Splore game selection menu, press the GameShell MENU button, then select "Exit to Splore". (You can also use the pause menu just to pause your game.)
To exit PICO-8 entirely and return to the GameShell Launcher, exit to Splore, then press MENU again and select "Shutdown PICO-8".
**Tip:** Be careful *not* to select "Exit to Console" from the shutdown menu. This puts PICO-8 in its game developer mode. It's a super fun mode, but you need a full keyboard to use it or get back out of it. Connect via ssh and run the `sudo reboot` command if you get stuck here.
_Tip:_ Be careful not to select "Exit to Console" from the shutdown menu. This puts PICO-8 in its game developer mode. It's a super fun mode, but you need a full keyboard to use it or get back out of it. Hold down the GameShell's power button to reset if you get stuck here.
Enjoy the games, and come visit the PICO-8 community in [the forum](https://www.lexaloffle.com/bbs/?cat=7) to learn more!
Enjoy the games, and come visit the PICO-8 community in the forum to learn more!
## Resources
Resources:
* [The PICO-8 website](https://www.lexaloffle.com/pico-8.php)
* [The PICO-8 forum](https://www.lexaloffle.com/bbs/?cat=7) ("BBS", where games are published)
* [The PICO-8 wiki](https://pico-8.wikia.com/wiki/Pico-8_Wikia)
* [LinuxCommand.org](http://linuxcommand.org/), for learning the Linux command line
* [Using Pico](https://itconnect.uw.edu/connect/web-publishing/shared-hosting/using-piconano/) (the file editor)
* [The PICO-8 forum ("BBS", where games are published)](https://www.lexaloffle.com/bbs/?cat=7)
* [Lazy Devs video of this installation procedure](https://www.youtube.com/watch?v=ltBVKFw88zw), including the v1.24 file renaming workaround
* [Lazy Devs video of additional steps](https://www.youtube.com/watch?v=4veRSqVHzoI) to enable volume buttons and upload PICO-8 cart files directly to the GameShell
* [Discussion of this tutorial](https://forum.clockworkpi.com/t/how-to-install-pico-8-on-gameshell/1012) in the ClockworkPi forum