Commit 0b44399c authored by Tim Allen's avatar Tim Allen

docs: Review and update docs for v107.

Changes include:

- The "Library" menu was replaced with the "Systems" menu
- The "Settings" menu was reorganised
- Game Boy rumble is now under the MBC5 "controller" for the cartridge "port",
  instead of being presented as a part of the base console
- Import instructions now mention that icarus ships with some firmware files,
  and describe the "Firmware" directory that icarus will use for firmware
  it needs.
- Apparently the correct name is "MSU1", not "MSU-1"
- v107 changes the way MSU1 data is stored in game folders
- PowerFest '94 import instructions removed, since I can't get it to work
  with v107
- Links to the official forum have been replaced with links to the unofficial
  forum archive, since the official forum is shutting down
- Links to Mercurial Magic updated to point at qwertymodo's archive, since
  hex_usr is no longer developing it
- Links to nSide updated, since hex_usr no longer uses GitHub.
- Windows build instructions now describe a compiler that is actually
  maintained, instead of stale TDM64-GCC.
- Linux build instructions now mention higan requires SDL 2.0.
- minor wording changes, typos, broken links fixed, etc.
parent 23dd2895
Pipeline #36810540 failed with stage
in 13 minutes and 10 seconds
......@@ -2,8 +2,8 @@ Contributing to higan
=====================
If you would like to propose a change to higan,
you should create an account on the [official forums][f],
go to the "Projects" forum and the "higan" sub-forum,
you should create an account on the [unofficial forums][f],
go to the "Projects" forum,
and post your idea in a new topic there.
[f]: https://board.byuu.org/
[f]: https://helmet.kafuka.org/bboard/
......@@ -27,11 +27,11 @@ Official higan resources
------------------------
- [Official homepage](https://byuu.org/emulation/higan/)
- [Official forum](https://board.byuu.org/viewforum.php?f=4)
Unofficial higan resources
--------------------------
- [Unofficial forum](https://helmet.kafuka.org/bboard/)
- Documentation for
[the current stable version][stadocs]
- [Source code repository](https://gitlab.com/higan/higan/)
......
......@@ -228,10 +228,13 @@ A: Try Settings -> Video -> Exclusive mode, then switch to fullscreen. This
Online Resources
----------------
Official homepage + forum:
Official homepage:
https://byuu.org/emulation/higan
https://board.byuu.org/viewforum.php?f=4
Unofficial forum:
https://helmet.kafuka.org/bboard/
Unoffical source code repository + documentation:
......
......@@ -8,5 +8,5 @@ checklink \
--summary \
--broken \
--location=http://127.0.0.1:8000/ \
--exclude 'github.com|board.byuu.org' \
--exclude 'github.com|board.byuu.org|helmet.kafuka.org' \
http://127.0.0.1:8000/
......@@ -53,7 +53,7 @@ higan can use a larger number of files per game.
For example,
higan's low-level emulation of Super Famicom co-processors
often requires [separate firmware files][firmware].
higan's [MSU-1 feature][msu1]
higan's [MSU1 feature][msu1]
supports up to 99 audio tracks per game,
and higan supports up to 133 save-states per game.
Thus,
......@@ -70,7 +70,7 @@ like save-states and the cheat database
to be kept separate from the game's actual data,
by putting it in a sub-folder.
[msu1]: ../guides/import.md#msu-1-games
[msu1]: ../guides/import.md#msu1-games
[firmware]: ../guides/import.md#games-with-co-processor-firmware
For a more detailed motivation for game folders,
......@@ -128,17 +128,21 @@ to all emulators that support them:
will create this file.
- `*.data.rom`, `*.program.rom`:
Files named like this are usually [co-processor firmware][firmware].
- `msu1.rom`:
Holds streamable data for [the MSU-1][msu1].
Files used by higan's [MSU1 extension][msu1]
are in the `msu1` sub-folder:
- `data.rom`:
Holds data that the MSU1 can stream.
- `track-*.pcm`:
Holds streamable audio for [the MSU-1][msu1].
Holds audio that the MSU1 can stream.
Files that are only useful to higan specifically
are placed in a `higan` sub-folder:
- `cheats.bml`:
All information present in
[the Cheat Editor](../interface/higan-tools.md#the-cheat-editor)
the [Cheat Editor](../interface/higan-tools.md#cheat-editor)
is stored here.
- `notes.txt`:
Everything entered in the [Game Notes] is stored here.
......
......@@ -4,8 +4,8 @@ is the folder where all the
When [icarus](../interface/icarus.md) imports a game,
it creates or updates
the corresponding game folder in the game library.
When you use the console sub-menu items
in [higan's Library menu](../interface/higan.md#the-library-menu),
When you use the items in
[higan's Systems menu](../interface/higan.md#the-systems-menu),
higan shows you the games for that console
that are already in the library.
......
......@@ -9,7 +9,7 @@ and to the console itself.
If you load a game into higan,
you can look at the game's manifest
by opening [the Tools menu](../interface/higan.md#the-tools-menu)
and choosing [Manifest Viewer](../interface/higan-tools.md#the-manifest-viewer).
and choosing [Manifest Viewer](../interface/higan-tools.md#manifest-viewer).
Why manifests?
--------------
......@@ -17,7 +17,7 @@ Why manifests?
For most consoles,
a manifest isn't strictly necessary:
the raw game data provides enough clues
for emulators to guess the circuit board configuration,
for emulators to guess the correct circuit board configuration,
or at least
to guess a *reasonable* configuration.
However,
......
......@@ -119,7 +119,7 @@ Manager states
--------------
higan's
[State Manager](../interface/higan-tools.md#the-state-manager)
[State Manager](../interface/higan-tools.md#state-manager)
allows you to create over a hundred save states,
and add a helpful description to each one.
......
......@@ -59,5 +59,5 @@ apologies to anyone we've missed!
For more information,
see the [credits thread](
https://board.byuu.org/viewtopic.php?f=4&t=1631&p=41575#p41575)
on the official forums.
https://helmet.kafuka.org/byuubackup2/[email protected]=4&t=1631.html)
on the archive of the official forums.
......@@ -5,12 +5,12 @@ playing audio,
and accepting input from game controllers.
Or rather,
there are many standards,
and different ones work best
and different ones work better
on different computers.
Therefore,
higan comes with "drivers"
for video, audio and input,
so you can find the one that works best for you.
so you can find the one that works best for your computer.
To see what drivers you're currently using,
or to choose different ones,
go to the [Advanced tab] of the Settings window.
......
......@@ -29,7 +29,7 @@ and (if possible) start playing.
**Note:**
If you want to import many games,
run icarus directly.
See [icarus] documentation for details.
See the [icarus] documentation for details.
To play a game for a particular console from your library,
open the [Systems menu],
......@@ -75,11 +75,11 @@ for yourself.
To import a game that requires co-processor firmware,
the easiest approach is to drop the firmware files into
icarus' `firmware` directory
icarus' `Firmware` directory
before importing the game.
The directory should be beside the icarus executable,
or it can be `%LOCALAPPDATA%\icarus\firmware` (on Windows)
or `~/.local/share/icarus/firmware/` (on Linux).
or it can be `%LOCALAPPDATA%\icarus\Firmware` (on Windows)
or `~/.local/share/icarus/Firmware/` (on Linux).
If the easy approach doesn't work for a particular game,
it may be because icarus has incorrectly guessed
......@@ -131,13 +131,13 @@ here's the firmware files you'll need:
</thead>
<tbody>
<tr>
<th scope="row">CX4</th>
<th scope="row">CX4<br><sup>See Note 1</sup></th>
<td><code>cx4.data.rom</code></td>
<td>3072</td>
<td><code>ae8d4d1961b93421ff00b3caa1d0f0ce7783e749772a3369c36b3dbf0d37ef18</code></td>
</tr>
<tr>
<th scope="row" rowspan=2>DSP1/1A<br><sup>See Note 1</sup></th>
<th scope="row" rowspan=2>DSP1/1A<br><sup>See Note 2</sup></th>
<td><code>dsp1.data.rom</code></td>
<td>2048</td>
<td><code>0b5da6533e55852ee8fc397977ec5576c5b9f1fb2e05656d8f87123a121b076e</code></td>
......@@ -148,7 +148,7 @@ here's the firmware files you'll need:
<td><code>269584b347a22953a2989494c850a7c1c027f4ca5add517a60e0c7d8833d0fac</code></td>
</tr>
<tr>
<th scope="row" rowspan=2>DSP1B<br><sup>See Note 2</sup></th>
<th scope="row" rowspan=2>DSP1B<br><sup>See Note 3</sup></th>
<td><code>dsp1b.data.rom</code></td>
<td>2048</td>
<td><code>8546cbac530830446bb8a277f6b139d4ad64d650bdbac7e4e150e2f095665049</code></td>
......@@ -228,10 +228,15 @@ here's the firmware files you'll need:
</table>
**Note 1:**
The CX4 firmware is shipped with higan,
because it just contains mathematical tables
and not a copyrightable program.
**Note 2:**
The DSP1 and DSP1A are physically different,
but the firmware inside is identical.
**Note 2:**
**Note 3:**
The DSP1B is very similar to the DSP1A,
but fixes some bugs.
Note that icarus' heuristics cannot distinguish between
......@@ -259,7 +264,7 @@ using the "Load ROM File ..." option in the [Systems menu]
but it does not include the correct firmware data,
nothing will happen,
and higan will just sit there
with "No cartridge loaded" in
with "Unloaded" in
[the status bar](../interface/higan.md#the-status-bar).
Once a game with co-processor firmware is imported,
......@@ -441,7 +446,14 @@ including the timing change.
Because the Super Game Boy cartridge includes
the original Game Boy hardware,
it needs a boot ROM:
it needs a boot ROM.
icarus includes these files
and can reliably decide when to use them,
so importing either Super Game Boy cartridge
is just like [importing a regular game](#regular-games).
In case you need to check the Super Game Boy boot roms,
here are their details:
<table>
<thead>
......@@ -468,11 +480,6 @@ it needs a boot ROM:
</tbody>
</table>
icarus includes these files
and can reliably decide when to use them,
so importing either Super Game Boy cartridge
is just like [importing a regular game](#regular-games).
To play a Game Boy game in Super Game Boy mode,
load the Super Game Boy cartridge like any other game.
higan will open another [filesystem browser]
......@@ -497,14 +504,14 @@ for details.
[blackcarts]: ../notes.md#playing-game-boy-color-games-in-game-boy-mode
MSU-1 games
-----------
MSU1 games
----------
The MSU-1 is a fictional expansion chip
The MSU1 is a fictional expansion chip
invented by higan's author byuu,
designed to allow the Super Famicom
to stream data and audio.
Although the MSU-1 is not specific
Although the MSU1 is not specific
to any particular storage medium,
it gives the Super Famicom similar capabilities
to CD-based add-ons
......@@ -512,32 +519,32 @@ like the Mega Drive's Mega CD
and the PC Engine's CD-ROM²,
such as CD-quality music and full-motion video.
Although the MSU-1 was invented for higan,
Although the MSU1 was invented for higan,
it is now supported by other Super Famicom emulators too.
The [SD2SNES] programmable cartridge
even allows you to play MSU-1 games on a real console.
even allows you to play MSU1 games on a real console.
There are a number of homebrew games
that make use of the MSU-1,
that make use of the MSU1,
and also mods for commercial Super Famicom games
that add higher-quality music and sometimes video.
One thing to be aware of
when importing an MSU-1 game
when importing an MSU1 game
is that early firmware versions of the SD2SNES
had a bug that caused MSU-1 music to play too quietly.
had a bug that caused MSU1 music to play too quietly.
Skipping over [the full details][msu1vol],
the short version is this:
- If offered the choice between "boosted" or non-boosted audio,
you want the non-boosted version.
- If an MSU-1 mod for a commercial game offers
- If an MSU1 mod for a commercial game offers
"emulator" and "hardware" versions of the patch file,
it means the audio tracks are already boosted.
- Some
[third](https://www.zeldix.net/t1265-#18320)
[parties](https://www.zeldix.net/t1339-#19818)
have created replacement, non-boosted audio tracks
for the most popular MSU-1 mods.
for the most popular MSU1 mods.
If the mod you want to play has a replacement pack,
use it with the "hardware" version of the patch.
- Even without access to non-boosted audio tracks,
......@@ -548,7 +555,7 @@ the short version is this:
distorting and clipping,
in which case try the "emulator" patch.
To import an MSU-1 game:
To import an MSU1 game:
1. If you have a single, large file
with the `.msu1` extension,
......@@ -560,11 +567,11 @@ To import an MSU-1 game:
2. Otherwise,
import the Super Famicom ROM with icarus,
[like a regular game](#regular-games).
- If this is a homebrew game with MSU-1 support,
- If this is a homebrew game with MSU1 support,
there will probably be an ordinary ROM
whose name ends in `.sfc`,
which is the file you want to import.
- If this is a commercial game modded for MSU-1 support,
- If this is a commercial game modded for MSU1 support,
there will probably be a patch file
whose name ends in `.ips` or `.bps`.
Get a copy of the correct version of the commercial game,
......@@ -574,14 +581,17 @@ To import an MSU-1 game:
see "One thing to be aware of..." above.
3. Find the game folder in the [game library]
that icarus created when it imported the game.
4. Copy the MSU-1 data file into the game folder.
- This should be named `msu1.rom`
4. Inside the game folder,
create a new folder named `msu1`.
5. Copy the MSU1 data file into the new `msu1` folder.
- This should be named `data.rom`
- If there's no file by that name,
look for a file with a `.msu` extension
look for a file named `msu1.rom`,
or a file with a `.msu` extension,
and rename it to `msu1.rom`.
- If there's no file ending in `.msu` either,
create an empty file named `msu1.rom`.
5. Copy the audio tracks into the game folder.
6. Copy the audio tracks into the game folder.
- If you have to choose between two sets of audio files,
see "One thing to be aware of..." above.
- These should be named
......@@ -601,13 +611,13 @@ To import an MSU-1 game:
this game probably just doesn't use the audio-playback feature.
Once the game folder is set up,
playing an MSU-1 game is just like
playing an MSU1 game is just like
[a regular game](#regular-games).
[SD2SNES]: https://sd2snes.de/
[Flips]: http://www.romhacking.net/utilities/1040/
[msu1vol]: http://blog.qwertymodo.com/2017/07/the-msu-1-volume-fiasco-explained.html
[Mercurial Magic]: https://github.com/hex-usr/Mercurial-Magic/
[Mercurial Magic]: https://github.com/qwertymodo/Mercurial-Magic
Patched games
-------------
......@@ -652,7 +662,7 @@ GBA games can be imported and played just like
Note that some GBA games
have trouble with
[in-game saves](../notes#in-game-saves-and-the-game-boy-advance).
[in-game saves](../notes.md#in-game-saves-and-the-game-boy-advance).
PowerFest '94
-------------
......@@ -670,85 +680,15 @@ switch between them after a specific time,
extract a score,
and display the combined total at the end.
icarus cannot automatically import
dumps of the PowerFest '94 ROMs,
but if you have the files,
you can import them manually.
You will need the following files:
<table>
<thead>
<tr>
<th>Part</th>
<th>Filename</th>
<th>Size (bytes)</th>
<th>SHA256</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">Scoring</th>
<td><code>program.rom</code></td>
<td>262144</td>
<td><code>2fc9dca305ce3fb2f1a476567de500d50c174fbfbabd32b1b91c3ea6a731b4a1</code></td>
</tr>
<tr>
<th scope="row">Super Mario Bros. - The Lost Levels</th>
<td><code>slot-1.rom</code></td>
<td>524288</td>
<td><code>7fd86113c5f95f794d65807bb75ab91c93c914670c27fc813ffa2ca20a48705e</code></td>
</tr>
<tr>
<th scope="row">Super Mario Kart</th>
<td><code>slot-2.rom</code></td>
<td>524288</td>
<td><code>19eb77affbf8dd068f5d79a3cf80a2084fd73237cd1ae4e47192b4422449e64a</code></td>
</tr>
<tr>
<th scope="row">Ken Griffey Jr. Presents Major League Baseball</th>
<td><code>slot-3.rom</code></td>
<td>1048576</td>
<td><code>d47bc9f9a6289c4f2e7f6bf74095f6ed36b1043a761e3e729ac9af2fc39ae062</code></td>
</tr>
</tbody>
</table>
Previous versions of higan
could emulate the PowerFest '94 cartridge,
but changes to higan's manifest system in v107
prevent PowerFest '94 from working in that version.
Support will likely be re-added in a future version,
but in the mean time you can use higan v106
and follow [that version's import instructions][pf94v106].
You will also need
the usual `dsp1.program.rom` and `dsp1.data.rom`
[co-processor firmware](#games-with-co-processor-firmware) files.
**Note:** the versions of
*Super Mario Kart*
and *Ken Griffey Jr...*
in *PowerFest '94*
are not the same as the stand-alone versions of those games.
To "import" *PowerFest '94*,
collect all the files mentioned above, then:
1. Inside [the game library](../concepts/game-library.md),
create the `Super Famicom` folder
(if it does not already exist).
2. Inside the `Super Famicom` folder,
create a `PowerFest '94.sfc` folder
(the `.sfc` extension is important,
but you can choose a different base name if you want).
3. Copy `program.rom` and the `slot-*.rom` files
into the `PowerFest '94.sfc` folder.
4. Copy the `dsp1.*.rom` files into the `PowerFest '94.sfc` folder,
but rename them to `upd7725.*.rom`.
To play *PowerFest '94*,
open the Library menu,
pick the Nintendo sub-menu,
then choose the Super Famicom sub-menu item
to open a filesystem browser listing
all the Super Famicom games in the library.
Select *PowerFest '94* from the list
and click the Open button,
or just double-click the game,
and it will begin playing.
[pf94v106]: https://higan.readthedocs.io/en/v106/guides/import/#powerfest-94
[filesystem browser]: ../interface/common.md#the-filesystem-browser
[Game Library]: ../concepts/game-library.md
......
......@@ -2,14 +2,14 @@ Most of the consoles higan emulates
were designed for low resolution NTSC televisions,
and their video output is chunky and blocky
by today's standards.
Video shaders customise how a console's video output
Video shaders customise how the emulated console's video output
is drawn to the computer screen,
and can clean up and smooth out the original video,
reproduce the scanlines and blurring of the original display,
or any other visual effect.
The available video shaders are listed in
the "Video Shaders" sub-menu of the [Settings menu].
the "Shader" sub-menu of the [Settings menu].
Which shaders are available depends on
the [video driver] higan is configured to use.
Most drivers only support these shaders:
......@@ -19,7 +19,8 @@ Most drivers only support these shaders:
the colour of the single nearest console pixel,
sometimes called "nearest neighbour" scaling.
This produces unnaturally crisp and blocky images.
- If you use [aspect correction or non-integral scaling][ac],
- If you enable Scale, Stretch, or Aspect Correction modes
in the Output sub-menu of the [Settings menu],
neighbouring console pixels may be drawn
with a different number of computer pixels due to rounding errors,
causing a distracting rippling effect.
......@@ -30,8 +31,6 @@ Most drivers only support these shaders:
sometimes called "bilinear" scaling.
This produces unnaturally blurry images.
[ac]: ../interface/higan-settings.md#video
In addition to those,
the OpenGL driver also supports custom shaders.
......@@ -90,7 +89,7 @@ you'll need to restart higan
for the change to take effect.
Open the Settings menu again,
choose the "Video Shader" sub-menu,
choose the "Shader" sub-menu,
and now the shaders you installed
should be listed at the bottom of the menu.
......
......@@ -64,17 +64,17 @@ by the time you read this,
and it may contain errors or omissions.
If you find something that's wrong,
or you have a suggestion,
post a message on the official higan forum.
post a message on the unofficial forum.
Official higan resources
------------------------
- [Official homepage](https://byuu.org/emulation/higan/)
- [Official forum](https://board.byuu.org/viewforum.php?f=4)
Unofficial higan resources
--------------------------
- [Unofficial forum](https://helmet.kafuka.org/bboard/)
- [Source code repository](https://gitlab.com/higan/higan/)
archives official higan releases
and WIP snapshots
......@@ -85,12 +85,12 @@ Unofficial higan resources
or smarter algorithms for scaling up to modern PC resolutions.
See [Using video shaders][shaders] below for details.
- [Mercurial Magic](https://github.com/hex-usr/Mercurial-Magic/)
is a tool for converting MSU-1 games and mods into a format
is a tool for converting MSU1 games and mods into a format
higan can use.
See [Importing MSU-1 games][msu1] for details.
See [Importing MSU1 games][msu1] for details.
[shaders]: guides/shaders.md
[msu1]: guides/import.md#msu-1-games
[msu1]: guides/import.md#msu1-games
There are also other projects
based on current or older versions of higan,
......@@ -113,7 +113,7 @@ that you might want to check out.
is a fork of bsnes v094
adapted to work as a
[libretro](https://www.libretro.com/) emulation core.
- [nSide](https://github.com/hex-usr/nSide)
- [nSide](https://gitlab.com/hex-usr/nSide)
is a fork of higan that greatly enhances
its NES emulation support,
and adds minor features to the other cores too.
......
......@@ -24,7 +24,7 @@ for the following libraries:
- Mesa
- gtksourceview 2.x
- Cairo
- SDL 1.2
- SDL 2.0
- libXv
- libAO
- OpenAL
......@@ -35,7 +35,7 @@ On a Debian-derived Linux distribution
you can install everything you need with a command like:
sudo apt-get install build-essential libgtk2.0-dev libpulse-dev \
mesa-common-dev libgtksourceview2.0-dev libcairo2-dev libsdl1.2-dev \
mesa-common-dev libgtksourceview2.0-dev libcairo2-dev libsdl2-dev \
libxv-dev libao-dev libopenal-dev libudev-dev
Once you have all the dependencies installed,
......@@ -53,7 +53,7 @@ being installed system-wide.
3. Type `cd ~/higan-src`
(or wherever you put the higan source)
and press Enter
4. Type `make -C higan` and press Enter
4. Type `make -C higan target=higan` and press Enter
to build the main higan executable
5. Type `make -C icarus` and press Enter
to build the icarus import tool
......@@ -68,7 +68,7 @@ as described in the previous section:
2. Type `cd ~/higan-src`
(or wherever you put the higan source)
and press Enter
3. Type `make -C higan install` and press Enter
3. Type `make -C higan target=higan install` and press Enter
to install higan and its supporting files
4. Type `make -C icarus install` and press Enter
to install icarus and its game database
......@@ -123,7 +123,7 @@ as installed by the above instructions:
2. Type `cd ~/higan-src`
(or wherever you put the higan source)
and press Enter
3. Type `make -C higan uninstall` and press Enter
3. Type `make -C higan target=higan uninstall` and press Enter
4. Type `make -C icarus uninstall` and press Enter
To remove higan's configuration,
......
......@@ -51,37 +51,57 @@ or by clicking the download button on the right-hand side of the web-page
and choosing an archive format.
You will need a C++ compiler to compile higan.
We recommend installing [TDM64-GCC][tdm],
preferably the latest version
but anything newer than 4.9 should be fine.
We recommend installing the latest version of [MinGW-W64].
higan does not support building with clang++
(Clang is still not quite there yet for Windows)
nor Microsoft Visual C++
(last we checked, it didn't support all the C++ features higan uses).
**Note:** Make sure you get TDM64-GCC,
not TDM-GCC.
When compiled in x86 (32-bit) mode,
higan may crash at startup
because gcc targeting x86 does not support
Windows' structured exception handling (SEH).
Also,
historically in x86 mode
gcc has miscompiled a part of the NES emulation core.
See the higan forum
[for](https://board.byuu.org/viewtopic.php?p=41977#p41977)
[details](https://board.byuu.org/viewtopic.php?p=42253#p42253).
Once you've installed the compiler,
open a command-prompt window,
[MinGW-W64]: https://mingw-w64.org/
MinGW-W64 is available in a number of variants,
and the installer should ask you which you want.