234 lines
14 KiB
Markdown
234 lines
14 KiB
Markdown
Cakefoot Arcade Operator's Manual
|
|
=================================
|
|
|
|
If Cakefoot is not installed yet, see [Installing Cakefoot as an Arcade Cabinet][0].
|
|
|
|
Once the game is installed and running in arcade-only mode, an operator's menu will be available. This menu can be used to set the amount of credits required to play, and to connect to a WiFi network for automatic updates.
|
|
|
|
Advanced operations can be performed by connecting a USB keyboard, exiting the game, and [opening the system terminal][6].
|
|
|
|
[0]: Installing_Cakefoot_as_an_Arcade_Cabinet.md
|
|
[6]: #advanced-system-configuration
|
|
|
|
Operator's menu
|
|
---------------
|
|
|
|
Press the operator's button on the inside of the Cakefoot arcade cabinet while Cakefoot is at the title screen. A menu with options specific to the arcade version should appear. In case the operator's button is not working or not installed, attach a USB keyboard to the computer and press the `F7` key.
|
|
|
|
<img src="Cakefoot_operator_menu.png" width=700 />
|
|
|
|
### Controls ###
|
|
|
|
Use up and down on the joystick to move between menu options. Press any button to start editing an option's value.
|
|
|
|
If the value is text or a number, the character input widget will appear. Use up and down to go through the list of characters. Select a character and press any button to add it to the option value.
|
|
|
|
The special characters backspace (⇦) and confirm (⇰) can also be input. Scroll to the end of the list to find those characters. Input a backspace character to delete a character. Input a confirm character to finish editing.
|
|
|
|
### Credits ###
|
|
|
|
The `Credits required per play` option is used to set the number of credits required to start the game. For example, if `4` credits must be inserted before the game should start, set the value to `4.0`.
|
|
|
|
The `Credit increase per event` option is used to set how much the credit amount should increase per trigger of the credit key. For example, if using tokens, and every token should be worth `2` credits instead of `1`, set the value to `2.0`.
|
|
|
|
The `Credit display name` option sets the name shown on the title screen to display how many credits the player has. For example, if using tokens instead of credits, the name could be set to `TOKEN`.
|
|
|
|
### WiFi ###
|
|
|
|
The `Wi-fi network` option is used to enter the name of a WiFi network to connect to. Uppercase, lowercase, space, and special characters are supported.
|
|
|
|
The `Wi-fi password` option is used to enter the password for the WiFi network. Uppercase, lowercase, space, and special characters are supported.
|
|
|
|
After changing the WiFi parameters, press `APPLY & SAVE` to apply the WiFi settings. There is currently no indicator of whether the WiFi is successfully connected, so make sure the parameters are input correctly. A future update is planned to display an icon when network connection is successful.
|
|
|
|
### Apply and save ###
|
|
|
|
Settings are not applied until the `APPLY & SAVE` button is pressed. To reset the changes, press the `EXIT` button twice to exit the menu without applying.
|
|
|
|
Advanced system configuration
|
|
-----------------------------
|
|
|
|
Some advanced operations are only possible to do from the system terminal. For example, clearing high scores and changing the screen resolution. These operations may be added to the game's interface in the future, but for now it is necessary to close Cakefoot and log into the system terminal.
|
|
|
|
The standard Cakefoot installation uses headless Linux, meaning there is no windowing system, only the system terminal. To quit to the terminal while Cakefoot is running, attach a USB keyboard to the computer and press `SHIFT+CTRL+Q`. The shift key prevents Cakefoot from trying to automatically relaunch after being closed, which is the default behavior. Once the game is closed, a login prompt will appear. If the password has not been changed, enter user `cakefoot` and password `forkitup`. See below for how to change the password after logging in. If it is not possible to get to the terminal using the key combination, see [Crash loop][4].
|
|
|
|
All edits must be made using the keyboard and terminal. For the operations in this section, the instructions contain exactly what to input into the terminal. However, it may still be useful to read [The Linux command line for beginners][1] if necessary.
|
|
|
|
[1]: https://ubuntu.com/tutorials/command-line-for-beginners
|
|
[4]: #crash-loop
|
|
|
|
### Reverting an update ###
|
|
|
|
If the system isn't working, it's possible a bad or broken update was installed. In that case, it may be possible to restore to a previously installed version.
|
|
|
|
Delete the WiFi connection so no further updates will be downloaded. Later, when a new, working update is available, WiFi can be restored. Enter the following, replacing the name with the actual name of the WiFi network currently in use.
|
|
|
|
> sudo nmcli connection delete "Spicy Meatball"
|
|
|
|
Once logged into the system, change to the Cakefoot install directory.
|
|
|
|
> cd ~/cakefoot
|
|
|
|
List the directory with details to see how the installation is currently set up to run.
|
|
|
|
> ls -l
|
|
total 23424
|
|
lrwxrwxrwx 1 cakefoot cakefoot 33 Feb 27 12:34 Cakefoot-linux -> Cakefoot-linux_arcade-1.5.0
|
|
drwxrwxr-x 7 cakefoot cakefoot 4096 Feb 27 12:34 Cakefoot-linux_arcade-1.4.2
|
|
drwxrwxr-x 7 cakefoot cakefoot 4096 Feb 27 01:58 Cakefoot-linux_arcade-1.4.3
|
|
drwxrwxr-x 7 cakefoot cakefoot 4096 Feb 27 02:53 Cakefoot-linux_arcade-1.5.0
|
|
|
|
`Cakefoot-linux` is a link to the folder corresponding to the version that will be launched at start up. In this case, it is linked to `Cakefoot-linux_arcade-1.5.0`. Assume 1.5.0 is a bad update, and use `ln` to link instead to 1.4.3, the previous version.
|
|
|
|
> ln -nsf Cakefoot-linux_arcade-1.4.3 Cakefoot-linux
|
|
> ls -l
|
|
total 23424
|
|
lrwxrwxrwx 1 cakefoot cakefoot 33 Feb 27 12:34 Cakefoot-linux -> Cakefoot-linux_arcade-1.4.3
|
|
drwxrwxr-x 7 cakefoot cakefoot 4096 Feb 27 12:34 Cakefoot-linux_arcade-1.4.2
|
|
drwxrwxr-x 7 cakefoot cakefoot 4096 Feb 27 01:58 Cakefoot-linux_arcade-1.4.3
|
|
drwxrwxr-x 7 cakefoot cakefoot 4096 Feb 27 02:53 Cakefoot-linux_arcade-1.5.0
|
|
|
|
`Cakefoot-linux` is now linked to `Cakefoot-linux_arcade-1.4.3`. This means the 1.4.3 version is active. Restart Cakefoot, and the system should be working again.
|
|
|
|
> systemctl --user restart cakefoot
|
|
|
|
When a new update is available, or it is confirmed that the issue was not the update, automatic updates can be resumed by reapplying the WiFi settings in the operator's menu.
|
|
|
|
### Switching between HDMI and AUX audio ###
|
|
|
|
The file `~/.asoundrc` is used to configure the sound card and sound device. The device index in this file can be either `0` to indicate AUX or `3` to indicate HDMI. Use the command below to set the sound device to HDMI. To use AUX instead, use `0` in place of `3`.
|
|
|
|
> echo -e 'defaults.pcm.!card 0\ndefaults.ctl.!card 0\ndefaults.pcm.!device 3\ndefaults.ctl.!device 3' > ~/.asoundrc
|
|
|
|
### Changing the resolution ###
|
|
|
|
The resolution can be set in the configuration file, using the parameter at `display > dimensions`. To override this parameter, add a custom configuration file to the `config/` folder. Configuration files are read in alphabetical order, so make sure the file name does not come before the config files already in the folder.
|
|
|
|
> ls -v ~/cakefoot/Cakefoot-linux/config
|
|
config.json config_arcade.json config_arcade_cabinet.json
|
|
> echo '{"display": {"dimensions": [1280, 720]}}' > ~/cakefoot/Cakefoot-linux/config/resolution.json
|
|
> ls -v ~/cakefoot/Cakefoot-linux/config
|
|
config.json config_arcade.json config_arcade_cabinet.json resolution.json
|
|
|
|
### Clearing scores ###
|
|
|
|
Scores are stored in a JSON file in the `storage/` folder. Move that file out of the directory into the home folder to save it as a backup. The game will automatically create a new arcade scores file the next time a score is submitted.
|
|
|
|
> mv ~/cakefoot/Cakefoot-linux/storage/cakefoot_arcade_scores.json ~/scores_backup.json
|
|
|
|
### Change password ###
|
|
|
|
To change the password for the `cakefoot` user, use the Linux `passwd` command. Enter `passwd` into the terminal and follow the prompts.
|
|
|
|
> passwd
|
|
|
|
### Other configuration ###
|
|
|
|
For advanced users, there are more parameters that can be edited in the configuration file. Use `less` to read the configuration or browse the file at [config.json][8]. Then use the same technique as in [Changing the resolution][7] to override a particular value.
|
|
|
|
> less ~/cakefoot/Cakefoot-linux/config/config.json
|
|
|
|
[7]: #changing-the-resolution
|
|
[8]: ../config/config.json
|
|
|
|
Help
|
|
----
|
|
|
|
### Crash loop ###
|
|
|
|
If the game crashes, only to be reloaded and then crash again repeatedly, the automatic reload service needs to be turned off. If Cakefoot loads to the title screen before it crashes, it's possible to quit the game and stop the service at the same time by pressing `SHIFT+CTRL+Q` on the title screen. When the game is quit with that key combination, it should not reload automatically.
|
|
|
|
If the game does not reach the title screen before crashing, it won't be possible to use the key combination to quit. In that case, the only option is to input commands directly into the terminal during the time between relaunches. Between relaunches, the login prompt should appear on screen before the next launch happens. While the login prompt is on screen, enter the username and password (the defaults are `cakefoot` and `forkitup`).
|
|
|
|
Once logged in, enter the following command into the terminal to stop the reload service.
|
|
|
|
> systemctl --user stop cakefoot
|
|
|
|
After that, the game should not relaunch automatically anymore. Most likely, the next step would be [Reverting an update][2].
|
|
|
|
[2]: #reverting-an-update
|
|
|
|
### Cakefoot does not load ###
|
|
|
|
Most likely, the best thing to do would be to follow the instructions in [Reverting an update][2]. There is also the option of looking at the logs to see if there is any helpful error message.
|
|
|
|
> journalctl --user -u cakefoot
|
|
|
|
### Updates do not download or install ###
|
|
|
|
Since there is no feature showing WiFi connectivity built into the game yet, the terminal must be used to test if there is a network connection available. `NetworkManager` is installed for managing WiFi connections. Try checking the network status to see if internet is working.
|
|
|
|
> nmcli general status
|
|
STATE CONNECTIVITY WIFI-HW WIFI WWAN-HW WWAN METERED
|
|
connected full enabled enabled missing enabled no (guessed)
|
|
|
|
The state should be `connected`, and connectivity should be `full`. If not, try looking up the available connections to see if the WiFi network has been added successfully.
|
|
|
|
> nmcli connection show --active
|
|
NAME UUID TYPE DEVICE
|
|
Spicy Meatball 745ae677-0b49-4bba-9111-eab25d7f94f7 wifi wlp0s20f3
|
|
|
|
This indicates "Spicy Meatball" is successfully connected. If the network isn't listed, try listing all connections.
|
|
|
|
> nmcli connection show
|
|
NAME UUID TYPE DEVICE
|
|
lo 9f35a928-850c-4c63-b82e-012ff7823f55 loopback lo
|
|
Spicy Meatball 745ae677-0b49-4bba-9111-eab25d7f94f7 wifi --
|
|
|
|
This indicates "Spicy Meatball" has been added to NetworkManager but is not connected. In that case, try deleting the connection before reconnecting it. If the network isn't listed, skip this step.
|
|
|
|
> nmcli connection delete "Spicy Meatball"
|
|
|
|
Add the network.
|
|
|
|
> nmcli device wifi connect "Spicy Meatball" password "B00M->H0t$4uc3"
|
|
Device 'wlp0s20f3' successfully activated with '3172be6c-6469-435b-8d23-05d9e8552b6f'.
|
|
|
|
The output should indicate the WiFi device was successfully activated. Restart Cakefoot and automatic updates should resume.
|
|
|
|
> systemctl --user start cakefoot
|
|
|
|
For further information, see [RedHat's NetworkManager manual][3].
|
|
|
|
[3]: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/7/html/networking_guide/sec-Configuring_IP_Networking_with_nmcli
|
|
|
|
### There is no sound ###
|
|
|
|
See [Switching between HDMI and AUX audio][9] for instructions on how to switch to a different sound device. If sound is still not working, there is a terminal GUI available for making sound adjustments. Try running `alsamixer` to see if there is a sound setting that needs to be adjusted. If the adjustments are successful, save the settings afterward.
|
|
|
|
> alsamixer
|
|
> sudo alsactl store
|
|
|
|
[9]: #switching-between-HDMI-and-AUX-audio
|
|
|
|
### High scores disappeared ###
|
|
|
|
This could be the result of file corruption during a save operation or an error during a software update. If there is an existing file at `~/cakefoot/Cakefoot-linux/storage/cakefoot_arcade_scores.json` that isn't being read into the game, it may contain corrupted data. First, backup the file in the home directory in case it can be restored later.
|
|
|
|
> ls ~/cakefoot/Cakefoot-linux/storage/
|
|
cakefoot_arcade_scores.json cakefoot_preferences.json cakefoot_progress.json cakefoot_stats.json
|
|
> mv ~/cakefoot/Cakefoot-linux/storage/cakefoot_arcade_scores.json ~/corrupt_scores_backup.json
|
|
|
|
Then, to see if there is a file that can be restored from a previous update, check for previous versions in the `~/cakefoot/` folder.
|
|
|
|
> ls ~/cakefoot/
|
|
Cakefoot-linux Cakefoot-linux_arcade-1.4.2 Cakefoot-linux_arcade-1.4.3
|
|
> ls ~/cakefoot/Cakefoot-linux_arcade-1.4.2/storage/
|
|
cakefoot_arcade_scores.json cakefoot_preferences.json cakefoot_progress.json cakefoot_stats.json
|
|
|
|
In this example, the 1.4.2 version has a scores file. Try copying that into the current version folder to see if any scores are displayed.
|
|
|
|
> cp ~/cakefoot/Cakefoot-linux_arcade-1.4.2/storage/cakefoot_arcade_scores.json ~/cakefoot/Cakefoot-linux/storage/
|
|
|
|
Try running the game to see if any scores were restored. If not, keep trying older versions if there are any left.
|
|
|
|
### Debugging ###
|
|
|
|
For advanced users, debug files can be generated with potentially helpful output for fixing errors. Use the technique described in [Changing the resolution][7] to enable debug files in the configuration. The values to set to `true` are `log > file enabled` and `log > debug to file`. After the game is run, log files should appear in the `log/` folder.
|
|
|
|
> echo '{"log": {"file enabled": true, "debug to file": true}}' > ~/cakefoot/Cakefoot-linux/config/log.json
|
|
> systemctl --user start cakefoot
|
|
> ls ~/cakefoot/Cakefoot-linux/log/
|
|
cakefoot_debug.log cakefoot_info.log
|
|
> less ~/cakefoot/Cakefoot-linux/log/cakefoot_debug.log
|