Actions, results, and types

Lookup tables for action names, the JSON shapes actions return, action types, and config field types. For how any of it fits together, see the concepts sections.

Paths

Junk Store does not use any other location. References to homebrew in older notes or internal strings are historical.

Actions

Action functions in a generated store script are named <Store>_<action>, for example Epic_install or Itch_getgames. The registered action names for a store are listed in the ACTIONS array at the end of its store.sh.

To see the exact list for a store on your machine:

grep '^function' ~/.local/share/junkstore/scripts/Extensions/Epic/store.sh

Actions every extension gets

Actions that appear based on configuration

Commonly seen action names on shipped stores include install, uninstall, verify, update, download, getdetails, getgames, getexelist, savesetting, savetabconfig, runlauncher, and supportsimport.

verify and update need no scripts of their own. They run the same downloader with a different mode, described in The third argument is a mode.

There is no launch action. Starting a game is handled by launcher.sh and the per platform scriptlets in launchers/, not by an action in store.sh. The runlauncher action is the entry point into that path.

Action results

Scripts talk to Junk Store by printing JSON on stdout. Two shapes you will use most:

Success

{"Type": "Success", "Content": {"Message": "Done"}}

Error

{"Type": "Error", "Content": {"Message": "Something went wrong"}}

Written in shell, with the escaping you need inside a double quoted string:

echo "{\"Type\": \"Success\", \"Content\": {\"Message\": \"EOS overlay Enabled\"}}"

If an action has nothing to report, printing nothing is acceptable.

Other Type values exist for structured content, for example GameGrid for a game list, GameDetails, GameImages, GameSize, Status, and the various editor types. The simplest way to get these right is to read the corresponding script in a shipped extension and match its output.

Action types

When an action is registered in the Generator it has a type, which mostly declares what kind of content the action returns. The ones you are most likely to meet:

Two caveats, because the field does not behave uniformly:

• Init, ScriptActions, and TabPage change what runs. Those three generate a call to the JSON helper rather than to the store dispatcher, so do not use them unless that is what you want.
• ScriptAction and ScriptActionConfirm are not yours to set. For script actions the type is derived from the confirm field, not from type. Set confirm to get a confirmation prompt.

See What type actually does for the detail.

Config field types

Config fields declared by an extension render as form controls:

For what each individual setting in the shipped config sections does, see Settings reference. For the structure these fields live in, see The config schema format.

The four Generator editors

The Generator exposes four editors, each covering one part of an extension’s definition:

Generator operations

Found in the Generator tab:

On adding games: there is no general form for entering a game by hand. The supported route is the file manager’s Add to Steam, which creates the game entry and its Steam shortcut from the file you selected. A .exe additionally gets its launcher set to Proton, with the executable, its directory and the install path recorded, so it is ready to run. Normally an extension finds its own games from the location you configured, so adding entries individually is the exception, not the workflow.

Sharing an extension

An extension exports to a single .json file, which is what you share, back up, and commit to version control.

This applies to extensions you created. The shipped Epic, Amazon, GOG, and Itch extensions are source available, not open source, and may not be redistributed. An export is a complete copy of everything in the extension, so exporting one of them and passing on the file redistributes their code just as surely as copying the scripts would. Back them up for your own use if you like; do not publish or pass on the result. See What you may and may not share.

Import and export are command line operations. The Generator menu lists “Import the preset from a file” and “Export the preset to a file”, but the working route is the command line, which takes the directory and name as arguments.

For export that is merely a detail. For import it is a deliberate speed bump. Importing an extension runs its code, so the friction is doing useful work: it means whoever imports has a terminal open, has the file on disk, and typed the extension’s name. A menu item invites tapping a thing somebody linked. Same operation, very different amount of thought in front of it.

JS="$HOME/.local/share/junkstore/junk-store Generator"

$JS importscripts MyStore              # edited scripts -> database
$JS exportpresetfile /path/to/dir MyStore   # database -> MyStore.json
$JS importpresetfile /path/to/dir MyStore   # MyStore.json -> database

Run importscripts before exporting, or you export the database’s older copy of your scripts rather than the ones you edited.

Download preset from server in the menu fetches extensions published by the Junk Store project.

importpresetfile runs somebody else’s code. An extension contains shell and Python scripts that Junk Store executes as you, unsandboxed, and some of them run simply because the extension is present. Only import from a source you trust, and read the scripts first if you are unsure. See Only import extensions from people you trust.

For the full workflow, including keeping the exported file in git, see Sharing and licensing.

Note this versions the scripts, not the Generator definition, so it is not a complete snapshot of the extension.

Progress reporting

Long running operations such as downloads report progress back to the UI. Rather than reproducing a format here that may differ per store, copy the approach from the downloader script of a shipped extension close to your use case, since that is the code the UI is known to work with.