Scripting

You can opt to have scripts launched at various points in Batocera. This will change the location you save the script to and how it opens.

Sometimes you just want to fire up one script after successfully booting, for example when you want to start up a VPN or other after-boot tasks. In order to do this, create a script text file at /userdata/system/custom.sh and give it the executable (x) attribute with chmod +x /userdata/system/custom.sh.

This script is the very last one that will be invoked by Batocera at boot time (check /etc/init.d/ to see all the modules that are loaded before then, S99custom is when the user script is launched). The filename must be custom.sh otherwise it will not be checked.

Make sure your script ends with Unix line terminators (LF), not Windows-style line terminators (CR/LF) otherwise the script will not launch. Use a real text editor to edit your scripts, especially if you edit them under Windows.

In Batocera v32 and higher, you can instead opt to launch a script early in the boot process, before much of Batocera has even begun loading. This is done by storing the script in the boot partition at /boot/boot-custom.sh. Keep in mind that you will be limited to more basic commands/modules, as most things have not loaded yet. Don't forget you still need to make it executable with chmod +x /boot/boot-custom.sh. The filename must be boot-custom.sh otherwise it will not be checked.

Precisely, this is the first thing executed once init.d has begun. This is before the network/share population/IR remote daemon have even loaded so capabilities are limited. Check /etc/init.d to see the exact order of all the modules have been loaded in (S00bootcustom is when the /boot/boot-custom.sh is executed).

This can be used to effectively patch and/or override the modules loaded by Batocera. Here are some examples that are only possible with this method:

  • Customize or disable S33disablealtfn to allow a certain text mode console on a particular TTY session.
  • Run fsck -a or e2fsck -p to harden the file system against data corruption in the case of a power cut/disconnection.

Batocera 5.23 and higher supports running a script right before a game launches and/or after a game is exited. Here are some examples:

  • Automatic controller setup
  • Automatic scraping for new games
  • Change screen resolution (though it might be better to use switchres for this)
  • Sync savestates to an external/network device
  • … give me your idea here

Place an executable script (can have any filename) with the correct setted shebang (first line!) or an executable binary into directory /userdata/system/scripts/.

You can add as many subfolders as you want, every script placed there will be executed. To distinguish between START or STOP condition the first argument parsed in the script have either of these flags:

  • gameStart is passed to your scripts if you select a game from EmulationStation (Game Starts!)
  • gameStop is passed to your scripts if you are going back from a game to EmulationStation (Game Stops!)

If you do not set cases for first argument, then the script is executed on every start and on every end of a game.

What is parsed

Table of parsed arguments in correct order and their functions:

Args. Parsed Parameter Usage
1 gameStart or gameStop To distinguish between START or STOP condition
2 systemName The system shortname as is in es_system.cfg, eg. atari2600
3 system.config['emulator'] The emulator settings, eg. libretro
4 system.config['core'] The emulator core you have chosen, eg. stella
5 args.rom The full rom path, eg. /userdata/roms/atari2600/Mysterious Thief, A (USA).zip

Real use cases

At first create the directory where the scripts need to be set up. Connect through SSH and type mkdir /userdata/system/scripts. After this we can set up our first script by typing nano /userdata/system/scripts/first_script.sh. The filename can be anything readable by bash.

Here's the template script:

first_script.sh
#!/bin/bash
#This is an example file how Events on START or STOP can be uses
#
 
#Set logfile location and filename
logfile=/tmp/scriptlog.txt
 
#Case selection for first parameter parsed
case $1 in
    gameStart)
        echo "START" > $logfile
        echo "$@" >> $logfile
    ;;
 
    gameStop)
        echo "END" >> $logfile
    ;;
esac

Make the script executable with chmod +x /userdata/system/scripts/first_script.sh

Now you can see a log file created /tmp/scriptlog.txt, that parsed all arguments in this file. This is just a small test of course. You can check out the SSH page and the usage of batocera-settings page for general and Batocera-specific commands.

  • launch_a_script.txt
  • Last modified: 11 days ago
  • by atari