JOLLYGOOD(6)

NAME
jollygood - The Jolly Good Reference Frontend

SYNOPSIS
jollygood [-abcfghorsvwx] [-a value] [-b frames] [-c corename] [-g value] [-o file] [-r value] [-s value] [-x value] [file ...]

DESCRIPTION
The Jolly Good Reference Frontend is the simplest possible frontend for The Jolly Good API. It is intended to remain this way, and to avoid unnecessary feature creep, ensuring that it is easy to learn from. In order to deliver a smooth and enjoyable experience, a few slightly more advanced features are required. In these instances, effort has been taken to ensure readability and understandability of the code that implements these concepts.

The options are as follows:

-a, --video value
    Specify which Video API to use.
        0 = OpenGL Core Profile
        1 = OpenGL ES
        2 = OpenGL Compatibility Profile

-b, --bmark frames
    Run N frames in Benchmark mode.

-c, --core corename
    Specify which core to use.

-f, --fullscreen
    Start in Fullscreen mode.

-g, --cheatauto value
    Auto-activate cheats if present.
        0 = Disabled
        1 = Enabled

-h, --help
    Show Usage.

-o, --wave file

-r, --rsqual value
    Resampler Quality (0 to 10).

-s, --shader value
    Select a Post-processing shader.
        0 = Nearest Neighbour (None)
        1 = Linear
        2 = Sharp Bilinear
        3 = Anti-Aliased Nearest Neighbour
        4 = CRT-Yee64
        5 = CRTea
        6 = LCD

-v, --verbose
    Enable verbose log output for core and frontend.

-w, --window
    Start in Windowed mode.

-x, --scale value
    Video Scale Factor (1 to 8).

  CONFIGURATION FILES
Configuration files are located in $XDG_CONFIG_HOME/jollygood/.

The following filenames are used:

settings.ini
    General settings.
input_sysname.ini
    Input definitions for a specific system.
corename.ini
    Core-specific overrides to general settings.

User data is located in $XDG_DATA_HOME/jollygood/.

The User data directory contains the following subdirectories:

assets/corename/
    User assets such as sample data for Nestopia JG.
bios/
    Directory the frontend will load BIOS images from.
cheats/corename/
    Directory the frontend will load Cheat files from.
save/corename/
    SRAM, Memory Card, or other types of save data.
screenshots/
    Screenshots with a timestamp and random number.
state/corename/
    Save States.

Cores may be used locally by placing their build output directories into a cores/ directory created in the jgrf source directory.

    $ mkdir cores
    $ cp -r /path/to/core/ cores/

Cores that exist locally will be preferred over cores installed system-wide.

  INPUT
Frontend Key Definitions:

ESC Quit
TAB Open Menu
`   Fast-forward
F1  Soft Reset
F2  Hard Reset
F3  Insert/Remove Media
F4  Switch Media (FDS Disks or CDs)
F5  Save State (Slot 0)
F6  Save State (Slot 1)
F7  Load State (Slot 0)
F8  Load State (Slot 1)
F9  Screenshot
F12 Toggle Cheats On/Off
F   Toggle Fullscreen/Windowed Mode
M   Toggle Audio Playback (Mute/Unmute)
Shift+<Port Number>
    Configure Input

Menu Key Definitions:

ESC Exit Menu
TAB/LEFT
    Back
ENTER/RIGHT
    Activate selected menu item
UP/DOWN
    Navigate Up and down

Input for games is not preconfigured. For example use Shift+1 for the first controller port and Shift+2 for the second controller port.

Effort has been made to ensure emulator cores know what devices must be plugged in. Console output will indicate which emulated device is plugged into which emulated port.

Axis and Button input is considered separate. Digital buttons cannot be assigned to emulated axes. This is a design choice. Use the ESC key to skip defining axes if you do not have a physical input devices with axes. Ideally, buy a budget USB gamepad with analog sticks/triggers if you want to play games that require analog input. The reverse, assigning physical axes to emulated digital buttons, is possible.

Force Feedback data is sent to the physical device that handles the emulated device's axis definitions. Currently, this only exists in PlayStation and Game Boy games. In the case of the Game Boy, there is only a single controller, so force feedback data is sent to this controller.

  SETTINGS
The General Settings configuration file accepts the following sections.

[audio]
    rsqual = <0-10>
        Resampler Quality <Default: 3>
[video]
    api = <0-2>
        Video Driver Profile <Default: 0>
            0 = OpenGL Core Profile
            1 = OpenGL ES
            2 = OpenGL Compatibility Profile
    scale = N
        Video Scale Factor <Default: 3>
    shader = <0-6>
        Post-processing shader <Default: 3>
            0 = Nearest Neighbour
            1 = Linear
            2 = Sharp Bilinear
            3 = AANN
            4 = CRT-Yee64
            5 = CRTea
            6 = LCD
    crtea_mode = <0-4>
        CRTea custom mode <Default: 2>
            0 = Scanlines
            1 = Aperture Grille Lite
            2 = Aperture Grille
            3 = Shadow Mask
            4 = Custom
    crtea_masktype = <0-3>
        CRTea custom mode settings <Default: 2>
            0 = Scanlines
            1 = Aperture Grille Lite
            2 = Aperture Grille
            3 = Shadow Mask
    crtea_maskstr = N
        CRTea mask strength <Default: 5>
    crtea_scantr = N
        CRTea scanline strength <Default: 6>
    crtea_sharpness = N
        CRTea sharpness. <Default: 7>
    crtea_curve = N
        CRTea Screen Curve Strength <Default: 2>
    crtea_corner = N
        CRtea Corner Size <Default: 3>
    crtea_tcurve = N
        CRTea Trinitron Curve Strength <Default: 10>
[misc]
    cheatauto = <0-1>
        Cheat Auto-activation at boot <Default: 0>
            0 = Disabled
            1 = Enabled
    corelog = <0-3>
        Core logging options <Default: 1>
            0 = Debug
            1 = Info
            2 = Warning
            3 = Error
    frontendlog = <0-3>
        Frontend logging options <Default: 1>
            0 = Debug
            1 = Info
            2 = Warning
            3 = Error
    textscale = N
        Text Scale Factor <Default: 2>

The settings may be overridden in a core specific configuration file. Additionally, you may add a section for Emulator Settings.

  CHEATS
When a core supports cheats, the cheat file must be named the same as the game, but with a file extension of ".json". The file must be located in the cheats directory for the core, for example:

    ~/.local/share/jollygood/cheats/corename/gamename.json

The file must be formatted as such:

    {"cheats":[
      {"codes":["CHEAT001"], "enabled":true, "desc":"Single-code Cheat"},
      {"codes":["CHEAT002"], "enabled":false, "desc":"Disabled Single-code Cheat"},
      {"codes":["CHEAT003", "CHEAT004"], "enabled":true, "desc":"Multi-code Cheat"},
    //  {"codes":["CHEAT005"], "enabled":true, "desc":"Commented Cheat"},
      {"codes":["CHEAT006"], "enabled":true, "desc":"Final Cheat has no comma"}
    ]}

The format for the cheat codes is different for each system, and some systems support multiple types of codes. All codes are represented as JSON strings.

ENVIRONMENT
jollygood supports the following environment variables.

XDG_CONFIG_HOME
    The XDG base directory. This is the path is used to find the frontend and core configuration files. Set by default to $HOME/.config/jollygood/.
XDG_DATA_HOME
    The directory for user-specific data files. This path is used to find data files used by the cores. Set by default to $HOME/.local/share/jollygood/.
JOLLYGOOD_CORE_DIRS
    A sequence of path prefixes to tell the frontend which directories to search for Jolly Good core modules. If set, these directories take precedence when searching for core modules to load. Include a colon (:) separator between the path names on a UNIX system, and use the semicolon (;) separator between path names on a Windows system.
JOLLYGOOD_ASSET_DIRS
    A sequence of path prefixes to tell the frontend which directories to search for asset-containing subdirectories. If set, these directories take precedence when searching for the location of core assets. Include a colon (:) separator between the path names on a UNIX system, and use the semicolon (;) separator between path names on a Windows system.

EXAMPLES

jollygood
    Print the frontend's help and exit.

jollygood file
    Run the rom file from the command line.

jollygood -c mednafen rom.sfc
    Run a Super Nintendo rom using the Faust emulator included in the Mednafen core instead of the default BSNES core.

jollygood -c bsnes "Super Game Boy (World) (Rev 2).sfc" rom.gb
    Run a Game Boy rom using the BSNES core and an auxiliary Super Game Boy Rom.

jollygood -c sameboy rom1.gb rom2.gb
    Run a multiplayer linked game with two Game Boy roms using the SameBoy core.

jollygood -a 2 file
    Run the frontend in a OpenGL Compatibility Profile.

time jollygood -b 1000 file
    Run the frontend for 1000 frames in Benchmark mode.

jollygood -f file
    Run the frontend in Fullscreen mode.

jollygood -o rom.wav file
    Output the rom audio to rom.wav.

jollygood -r 3 file
    Run the frontend with Resampler Quality set to 3.

jollygood -s 5 file
    Run the frontend using the CRTea shader.

jollygood -x 3 file ...
    Run the frontend wth a Video Scale Factor of 3.

Example settings.ini configuration file for the jollygood frontend.

    [audio]
    ;N = Resampler Quality (0-10)
    rsqual = 3
    [video]
    ;0 = OpenGL Core Profile, 1 = OpenGL ES, 2 = OpenGL Compatibility Profile
    api = 0
    ;0 = Disable, 1 = Enable
    fullscreen = 0
    ;N = Scale video output by N (1-8)
    scale = 3
    ;0 = Nearest Neighbour, 1 = Linear, 2 = Sharp Bilinear, 3 = AANN,
    ;4 = CRT-Yee64, 5 = CRTea, 6 = LCD
    shader = 3
    ; Settings for CRTea
    ;0 = Scanlines, 1 = Aperture Grille Lite, 2 = Aperture Grille,
    ;3 = Shadow Mask, 4 = Custom
    crtea_mode = 2
    ; Settings for CRTea Custom Mode
    ;0 = Scanlines, 1 = Aperture Grille Lite, 2 = Aperture Grille, 3 = Shadow Mask
    crtea_masktype = 2
    ;N = Mask Strength
    crtea_maskstr = 5
    ;N = Scanline Strength
    crtea_scantr = 6
    ;N = Sharpness
    crtea_sharpness = 7
    ;N = CRT Screen Curve Strength
    crtea_curve = 2
    ;N = CRT Corner Size
    crtea_corner = 3
    ;N = Trinitron Curve Strength
    crtea_tcurve = 10
    [misc]
    ;0 = Disabled, 1 = Enabled
    cheatauto = 0
    ;0 = Debug, 1 = Info, 2 = Warning, 3 = Error
    corelog = 1
    ;0 = Debug, 1 = Info, 2 = Warning, 3 = Error
    frontendlog = 1
    ;N = Text Scale
    textscale = 2

Example jollycv.ini configuration file for the JollyCV core.

    [jollycv]
    ;0 = Show Overscan, 1 = Mask Overscan
    mask_overscan = 0
    ;0 = TeaTime, 1 = SYoung
    palette = 0
    ;N = Resampler Quality (0-10)
    rsqual = 3
    ;0 = NTSC, 1 = PAL
    region = 0

Example input_snes.ini configuration file for all Super Nintendo emulators.

    [snespad1]
    Up = j0a1-
    Down = j0a1+
    Left = j0a0-
    Right = j0a0+
    Select = j0b4
    Start = j0b5
    A = j0b1
    B = j0b2
    X = j0b0
    Y = j0b3
    L = j0b6
    R = j0b7

Example cheats/bsnes/Super Castlevania IV (USA).json cheat file for the Super Castlevania IV (USA).sfc rom and the BSNES core.

    {"cheats":[
      {"codes":["DD24-AFD7"], "enabled":true, "desc":"Fully Powered Up Whip With First Power Up"},
    //  {"codes":["bbb3-d40f"], "enabled":true, "desc":"99 Hearts"}
    //  {"codes":["0094EAFF"], "enabled":true, "desc":"1st heart = 99 Hearts"},
      {"codes":["028005=80"], "enabled":true, "desc":"Stop Timer"}
    ]}

AUTHORS
-nosplit The Jolly Good API and Reference Frontend were written by Rupert Carmichael.

BUGS
Issue tracker: https://gitlab.com/jgemu/jgrf/-/issues