JSRF-PC for Linux (x86_64)
==========================

Jet Set Radio Future, statically recompiled and running natively.
https://github.com/spriteice/JSRF-PC

You need your own copy of the game -- the standalone US disc (not the Sega GT
2002 + JSRF combo disc, whose JSRF is a different build). This package holds
none of the game: no game files, no textures, no music, no video, and none of
its code. The first time it starts, it builds the engine from your copy (see
The first start below).


What you need
-------------
- A 64-bit PC (x86_64) with a recent Linux: glibc 2.34 or later, which means
  Ubuntu 22.04, Debian 12, Fedora 36, Linux Mint 21, current Arch, SteamOS,
  or anything newer.
- Graphics drivers with OpenGL 3.3 (Mesa or NVIDIA's, on any GPU from the last
  ten years).
- A desktop session, X11 or Wayland. Sound goes through PipeWire, PulseAudio,
  or ALSA.
- Your game files: an image of your own disc (an XISO or a full disc image,
  usually .iso), or the folder its files were extracted into -- the one with
  default.xbe, Media/, and the rest in it.


Playing
-------
1. Extract this archive anywhere.
2. Run ./jsrf-pc
3. The first time, it asks where the game is: pick the folder that contains
   default.xbe, or the folder your disc image (.iso) is in. (With zenity or
   kdialog installed you get a folder picker; otherwise it asks in the
   terminal.) An image is unpacked once, by the game itself -- nothing else to
   install. It remembers the choice. You can also give the folder or the
   image on the command line:  ./jsrf-pc /path/to/game.iso
   If the files are not the right ones (another build of the game, another
   game's disc, a zip), it says what they are.

   ./jsrf-pc --install     adds JSRF-PC to your applications menu
   ./jsrf-pc --scale N     internal resolution, 1 to 6 (default 3); remembered
   ./jsrf-pc --fullscreen  always starts full screen
   ./jsrf-pc --choose      asks where the game is again
   ./jsrf-pc --version     which version this is


The first start
---------------
This package has no engine yet: the first time you run ./jsrf-pc, it builds
the engine from your own copy of the game, once. It asks first:

  "No matching binary detected. Build now with local tools?" when a tools
  folder is beside jsrf-pc. It comes from the release's tools archive,
  JSRF-PC-tools-linux-x86_64.tar.gz: extract it here, where it makes one
  folder, tools. Nothing is downloaded.

  "No matching binary detected. Download tools now and build?" when there is
  none. The tools come from their own sites: Python from GitHub, and capstone
  and Zig from PyPI, about 100 MB, each checked by its SHA-256.

Yes goes on: it asks where the game is (as in Playing above), translates the
game's default.xbe into C, and compiles it, with one progress bar. It takes a
few minutes (2 to 3 on the PCs tested). No closes the window, and the game
doesn't start. Only the tools in the tools folder are used, whatever else is
on the PC, and nothing is installed: it all stays in this folder.

Then it offers to delete the tools and the code made from your game, a few
hundred MB. The engine (bin/jsrf_recomp) stays. Keep them to build a new
release faster. The engine is checked against the one this release was tested
with: if yours differs, as another copy of the game can make it, it says so
and asks whether to play anyway.

A new release extracted over this folder builds its own engine at its first
start. The build's log is build/build.log.


Controls
--------
Controller: any pad SDL knows -- Xbox, PlayStation, Switch Pro, Steam Deck,
and many more.

Keyboard (by key position, so W A S D on QWERTY is Z Q S D on AZERTY):

  W A S D      move (left stick), menus     Arrow keys  camera (right stick)
  Space or J   A -- jump                    K           B
  H            X                            L           Y
  E            R trigger -- talk, spray     Q           L trigger
  R            Black                        F           White
  Return       Start                        Esc         Back
  C / V        left / right stick click

  F1                  the in-game menu (also Back on a controller, which is
                      then the menu's alone): File, Display, Graphics,
                      Audio, Controller, and Developer
  F11 or Alt+Return   full screen or a window, full screen by default;
                      remembered
  F10                 4:3, or widescreen at your screen's own shape, the
                      default (Display > Aspect ratio has 16:10, 16:9 and
                      21:9 too): a wider
                      view, not a stretch; the HUD keeps its shape and sits
                      at the screen's edges, the pause menus and the race
                      previews are laid out across the screen, the garage's
                      menus and VS mode's setup screen carry their colours
                      on to its edges, the result screens' banner, time and
                      choices sit at the right edge, the title fills the
                      screen, its opening's bars sweeping in from its
                      edges; remembered
  F9                  resolution: the game is drawn at 1x to 6x the Xbox's
                      640x480 (3x by default), up to 3840x2880, and as much
                      wider as the shape in widescreen (5120x2880 at 16:9);
                      remembered. The game restarts to apply it, so save
                      first.
  F8                  free camera: the right stick turns the camera around
                      the player; remembered (see Free camera below). R3 on
                      a controller does the same

File > Presets in the in-game menu sets many settings at once. Xbox mode is
the game as the Xbox runs it: 4:3 at 1x, with everything JSRF-PC adds to how
it looks and plays turned off, but the audio effects, which are the console's
own. JSRF-PC default is the settings a new install starts with. Max quality is
JSRF-PC default with the render scale, draw distance, anisotropic filtering,
Upscaling's Menus and HUD, Textures and Graffiti, and both anti-aliasings at
their most, as far as the graphics card goes, and Far buildings and Far
shadows at 3x: it asks a lot of the computer. A preset sets every setting but
Developer's: each one also puts the game full screen, Upscaling's Cleanup as
a new install has it, and the free camera's own settings back to their
defaults. The one ticked is the one your settings match, if any. The game
restarts if the render scale, the shader cache or the audio effects change,
so save first.

Display > HUD in the in-game menu has HUD scale, which draws the HUD at
0.5x to 1.5x its size (1x, the default), a tenth at each - or +, and
Disable HUD, which hides it. Each piece keeps its distance from the screen's
edges and grows or shrinks from there; the signs and the counter in the
middle of the screen grow or shrink in place. Both change straight away, and
are remembered as hudscale= (0.5 to 1.5) and hudoff= (1 for hidden) in the
settings file. In split screen the HUD keeps its own size, though Disable HUD
still hides it.

Display > Draw distance in the in-game menu is how far away the game draws
the things in its world: crowds, spray cans, props you can knock over,
traffic, the police and the race's checkpoints. 1x is the game's own
distances, 2x (the default) to 4x twice to four times them, and Unlimited as
far as the camera sees. It changes straight away, asks more of the computer the
further it goes, and is remembered as drawdistance= in the settings file (0
for 1x to 4 for Unlimited). Above 2x it will struggle on weak hardware.

Display > Building distance > Far buildings in the in-game menu draws more
of the map, with the things in it, so buildings further off don't pop in as
you come near. The game splits each map into areas, and draws only the ones
the area the camera is in lists. Off is the game's own; 1x, 2x and 3x (the
default) draw what the game would show from the areas one, two or three
areas ahead; and All draws every area the game ever shows, which can put a
part of the map in view where the game never shows it, such as the top of
Dogenzaka Hill in the sky at its bottom. It changes straight away, asks more
of the computer the further it goes, and is remembered as farbuildingsahead=
in the settings file (0 for Off to 4 for All).

Display > Building distance > Far shadows, below Far buildings, draws the
shadows of the areas Far buildings adds too, as many areas ahead as its own
choice, Off to All, and never further than Far buildings, so they don't pop
in as you come near, at the cost of minor visual glitches, such as patches
of light in shadows that move with the camera. Off, those areas have no
shadows until you're near enough for the game to show them itself. 3x by
default. It does nothing with Far buildings off, changes straight away, and
is remembered as farshadowsahead= in the settings file (0 for Off to 4 for
All). Before b2.1-hotfix the two were on or off, remembered as farbuildings=
and farshadows=: until you choose again, 1 there reads as 3x and 0 as Off.

Display > Skips > Skip intro in the in-game menu leaves out the logos and the
graffiti disclaimer the game opens with: it starts at the title screen's
loading. Off by default, so the intro plays as on the Xbox. It is remembered
as skipintro= in the settings file (0 or 1).

Display > Enhancements > Music info in pause in the in-game menu shows the
song playing, its number, title and artist, in both pause menus, on the left,
above Rotate map. It follows the songs of the street mixes too, and shows
nothing for the title's and the story's own music. On by default. It changes
straight away, and is remembered as musicinpause= in the settings file
(0 or 1).

Display > Enhancements > See through fix in the in-game menu shows
characters and dynamic world objects through glass and water, tinted by
them: the game draws them after the glass, and on the Xbox the glass hides
them, as the crowd behind a shop's window. Faded characters still hide what
is behind them, as on the Xbox. On by default. It changes straight away, and
is remembered as seethru= in the settings file (1 or 0).

Graphics > Anti-aliasing (MSAA) in the in-game menu smooths jagged edges:
Off (the default), 2x, 4x, or 8x, as far as the graphics card goes. It changes
straight away, with no restart, and is remembered as msaa= in the settings
file (0, 2, 4, or 8). More asks more of the graphics card, the more so at the
higher resolutions.

Graphics > Anti-aliasing (SMAA) in the in-game menu smooths jagged edges
with a quick pass over each finished frame, at much the same small cost
whatever is on screen. It smooths the HUD too. It works alone or on top of
MSAA. On by default; it changes straight away, with no restart, and is
remembered as smaa= in the settings file (0 or 1).

Graphics > Anisotropic filtering in the in-game menu keeps textures sharp
where they are seen at a steep angle, such as streets and walls running into
the distance: Off, 2x, 4x, 8x (the default), or 16x, as far as the graphics
card goes. It changes straight away, with no restart, though the textures it
reaches take a moment to load again, and is remembered as aniso= in the
settings file (0, 2, 4, 8, or 16). It leaves things that face the screen,
such as the HUD, as they were.

Graphics > Upscaling > Menus and HUD in the in-game menu draws the menus,
text, HUD and icons from sharper copies of the game's art: Off, 2x, 4x (the
default), or 8x. The graphics card makes each copy the first time that art is
shown, a few a frame. It helps from render scale 2x up; at 1x it makes
nothing, as the art is drawn at its own size there. It changes straight away,
with no restart, and is remembered as upscale_2d= in the settings file (0, 2,
4, or 8). Each size suits a render scale: 2x for 2x, 4x for 3x and 4x, and 8x
for 5x and 6x, whose copies take the most memory.

Graphics > Upscaling > Textures in the in-game menu draws the textures of the
3D world (walls, the ground, signs and the characters) from sharper copies:
Off, 2x, 4x (the default), or 8x. The graphics card makes the copies in a
level's first moments, a few a frame. They show where a surface comes close
enough to the camera for its texture to be enlarged, at any render scale and
more so the higher it is. Distant surfaces, and cut-out edges such as fences,
look as they always have. It changes straight away, with no restart, and is
remembered as upscale_3d= in the settings file (0, 2, 4, or 8). No copy is
larger than 2048 a side, so 8x enlarges the larger textures 4x. The copies
take up to 4 GB of the graphics card's memory, 1 to 2.5 GB at 4x in play;
whatever doesn't fit keeps the game's own textures.

Graphics > Upscaling > Graffiti in the in-game menu draws the graffiti tags
from sharper copies: Off, 2x, 4x (the default), or 8x. The tags come 16 to a
sheet of 1024 x 1024, and the graphics card makes a sheet's copy the first
time it is drawn, after the 3D world's; the garage's graffiti picker has its
copy made as it draws it, which can pause the menu for a moment. It changes
straight away, with no restart, and is remembered as upscale_graffiti= in the
settings file (0, 2, 4, or 8). The copies take up to 1 GB of the graphics
card's memory, apart from Textures': about 85 MB a sheet at 4x and 340 MB at
8x.

Graphics > Upscaling > Sharpness in the in-game menu sets how crisp the edges
in the 2D, 3D and graffiti copies are: Soft, Normal (the default), or Sharp.
Normal is Super-xBR as its author set it; Sharp draws edges crisper and Soft
softer, neither with halos. It changes straight away, with no restart, making
every copy again, which can pause the game for a moment, and is remembered as
upscale_sharpness= in the settings file (0, 1, or 2).

Graphics > Upscaling > Edge strength in the in-game menu sets how faint a
diagonal edge the 2D, 3D and graffiti copies follow: Soft, Normal (the
default), or Strong. Normal is Super-xBR as its author set it; Strong follows
fainter diagonals too, for smoother lines in fine detail, and Soft only clear
ones, blending the rest. It changes straight away, with no restart, making
every copy again, which can pause the game for a moment, and is remembered as
upscale_edge_strength= in the settings file (0, 1, or 2).

Graphics > Upscaling > Cleanup in the in-game menu cleans the game's textures
up before the copies are made, with two ticks, each off by default: DXT
deblock smooths the faint steps where a DXT texture's 4x4 blocks meet, and
De-dither smooths the dot patterns of 16-bit and DXT textures. Each leaves
larger differences, edges in the picture, as they are, and neither changes a
texture's see-through parts. A change takes effect straight away, with no
restart, making every copy again, which can pause the game for a moment.
Each preset in File > Presets turns both off. They are remembered as
upscale_deblock= and upscale_dedither= in the settings file (0 or 1).

Graphics > Shader cache in the in-game menu (on by default) keeps the shaders
the game builds, in the cache folder. Each time the game starts, they are all
built again before it begins, behind a progress bar, so none are built while
you play. It is remembered as shaders= in the settings file (1 or 0).
Changing it in the menu restarts the game, after asking, as a new resolution
does.

Audio > Audio effects in the in-game menu (on by default) adds our own
versions of the console's sound effects: the 3D sounds placed to your left or
right as the game sets them, the characters' voices kept on them as they
move, the reverb the game sets for a place, as in the sewers, and a limiter
of their own for the 3D sounds, so a busy moment no longer turns the music
and voices down. Turned off, the sound is as before them. It is remembered as
audioeffects= in the settings file (1 or 0). Changing it in the menu restarts
the game, after asking.

Developer > Log to file in the in-game menu (on by default) writes the game's
output to last-run.log. Turned off, nothing more is written to it until it is
turned on again, and what is there already stays. It changes straight away and
is remembered as logging= in the settings file (1 or 0). Developer > Logging
adds the engine's own diagnostic lines to the log, for bug reports,
Developer > Engine switches turns parts of the engine off or changes how they
work, to compare, Developer > Performance has what the engine does for speed,
each on by default and ticked, to untick and compare: Use P cores (the game on
the processor's fast cores), GPU queue, Display pacing, Sleep while waiting for
the GPU, and Compressed textures direct, and Developer > Experimental, when
there is anything in it, tries out changes to how the game runs. Each row
stands for an environment variable, kept in developer.cfg beside the settings
file as NAME=1 or NAME=0, and applies from the next start: File > Restart
restarts the game, after asking.
Developer > Purge shaders asks first, then restarts the game and deletes the
shader cache as it starts: each shader is built again when the game first
needs it.


Free camera
-----------
F8, R3 on a controller, or freecam=1 in the settings file, gives the right
stick to the camera: it turns around the player, and forward is wherever it
looks. The L trigger puts it back behind the player, as it does the game's
camera. Spraying graffiti doesn't turn it to the wall, and talking to
someone doesn't turn it to them. It steers only the camera of the skater you
control: when the game moves a skater by itself, as when a scene follows
another skater, the game's own camera shows it. Pausing keeps the view. F8
and R3 are remembered. The settings file (see "Where things are kept") also
takes these, one per line, with no spaces around "=". The values shown are
the defaults, which a key that is left out, or out of range, gets:

  freecam=0          1: on
  invert_x=0         1: right turns the view left
  invert_y=0         1: up tilts the view down
  sensitivity_x=5    left-right speed, 1 to 10: 36 degrees a second per step
  sensitivity_y=5    up-down speed, 1 to 10
  deadzone=0.15      how far the stick moves before the camera does, 0 to 1
                     (0.15 is 15%)
  autocentre=0       auto centre: once the right stick is let go, the view
                     eases back behind the player. 0 off, 1 mild (after 2
                     seconds, slowly), 2 medium, 3 high (after a second),
                     4 aggressive (after half a second, quickly)

The in-game menu's Controller menu has all of these too, and keeps them here
as F8 does: with no keyboard (Steam's Game Mode), Back opens it, and R3
turns the free camera on and off. The game does not use R3.

Controller > Default cam fix in the in-game menu keeps the game's own camera
from showing through a wall beside it, which happens on the Xbox too and more
in widescreen: near a wall, the view shifts a little to the side, or in. While
you spray graffiti, the game frames the shot as on the Xbox. On by default;
off, the game's camera is as on the Xbox. It changes straight away, and is
remembered as dcamfix= in the settings file (0 or 1).


Where things are kept
---------------------
  Saves     in the game folder, under UDATA (where an Xbox keeps them): copy
            UDATA somewhere to back your progress up
  Settings  ~/.config/jsrf-pc/settings
  Cache     ~/.local/share/jsrf-pc/save
  Logs      ~/.local/state/jsrf-pc/last-run.log (and logs/)


Portable mode
-------------
Make a folder named "portable" next to jsrf-pc, and everything is kept
in it instead -- nothing in your home folder, nothing in the game folder:

  portable/settings.cfg   settings
  portable/saves/         saves (UDATA and TDATA): back this folder up
  portable/logs/          last-run.log and the logs before it
  portable/cache/         the game's cache: safe to delete
  portable/games/         disc images unpacked in portable mode

The first time, it asks where the game is again, and copies the saves it
finds in the game folder into portable/saves (the originals stay). A game
folder inside this folder is remembered relative to it, so the whole folder
can be moved, to an SD card for instance.

To update, extract the new version over this folder, or move portable/ into
the new one: deleting the folder deletes your saves with it. --install does
not work in portable mode (the applications menu is in your home folder).
Graphics drivers, sound, and the folder picker keep their own small files in
your home folder as they do for any program.

Found a bug? Open an issue on GitHub with last-run.log and what you were doing.


Steam Deck
----------
Not tested yet, but it should work: in Desktop Mode, run ./jsrf-pc once
to pick the game folder, then add jsrf-pc to Steam as a non-Steam game.


Legal
-----
Jet Set Radio Future is (c) SEGA. This is an unofficial fan project, not
affiliated with or endorsed by SEGA. This package holds the engine's runtime
and what it takes to build the rest, and nothing of the game: no game data and
none of its code. The engine the first start builds from your copy, the
runtime with the game's code machine-translated to native code, is made on
your PC and stays there.

Licences: GPL version 2 or later for this project's own code, with an
additional permission for the game's own code, which isn't under it; MIT for
the code from JSRF Unleashed and xboxrecomp; LGPL-2.1-or-later for the MCPX
audio-processor code extracted from xemu; the bundled SDL2 library is under
the zlib licence. The tools the first start uses keep their own licences, in
the tools folder: Python under the PSF licence, capstone under the BSD
licence, and Zig under the MIT licence, with those of LLVM and the C libraries
it carries. See the licences/ folder. Source code:
https://github.com/spriteice/JSRF-PC, a fork of JuMatt's JSRF Unleashed:
https://github.com/JuMatt/JetSetRadioFuture-Unleashed
