Commit 30ed7f7e authored by Tim Allen's avatar Tim Allen

Remove higan docs from the bsnes fork.

parent e0567218
#!/bin/sh
# This uses the official W3C link-checker tool:
#
# https://github.com/w3c/link-checker
#
checklink \
--summary \
--broken \
--location=http://127.0.0.1:8000/ \
--exclude 'github.com|board.byuu.org|helmet.kafuka.org' \
http://127.0.0.1:8000/
A game folder
is higan's way of grouping all
the information and resources required
to properly emulate a particular game.
For example,
to represent a Super Famicom game named `dkc3`,
higan would create a game folder named `dkc3.sfc`,
and inside it store the game data as `program.rom`
and the save data as `save.ram`:
```python
+- Super Famicom
|
+- dkc3.sfc
|
+- program.rom
|
+- save.ram
```
In contrast,
other emulators typically
group resources related to a game
by requiring that every file has the same base name
but different file extensions.
For example,
if another emulator loaded the game `dkc3.sfc`
it might store the save data in `dkc3.srm`:
```python
+- Super Famicom
|
+- dkc3.sfc
|
+- dkc3.srm
```
Why game folders?
-----------------
A file extension doesn't offer
much room for description,
so the traditional name-based-grouping system
only really works when games use a small number of files,
Also,
since file extensions traditionally describe
the format of the file in question,
it also means a game can't use
two or more files in the same format.
Compared to other emulators,
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 [MSU1 feature][msu1]
supports up to 99 audio tracks per game,
and higan supports up to 133 save-states per game.
Thus,
higan suffers from the limitations of name-based-grouping
more than most.
higan's game folders allow a game
to have unique, descriptive filenames
for all its resources,
and for each file to use the extension
that's most appropriate.
They also allow emulator-specific extras
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#msu1-games
[firmware]: ../guides/import.md#games-with-co-processor-firmware
For a more detailed motivation for game folders,
see [Game Paks on the higan website][gp].
[gp]: https://byuu.org/emulation/higan/game-paks
What's in a game folder?
------------------------
A game folder collects all the information relevant
to emulating a particular game.
Not all of the following files
are relevant for every console,
or even for every game on a console,
but they may be present under particular circumstances.
All the files directly in the game folder
are expected to be useful
to all emulators that support them:
- `manifest.bml`:
The [manifest](manifests.md) for this game folder.
- `program.rom`:
For most consoles,
this contains
the executable instructions and graphics data
from the cartridge's ROM chips.
For the Famicom,
this contains only the executable instructions.
- `character.rom`:
For the Famicom,
this contains only the graphics data
from the cartridge's ROM chips.
- `ines.rom`:
While other consoles typically include enough hints
in `program.rom` for icarus to guess a working manifest,
the Famicom does not.
Famicom games not stored in game folders
typically include an "iNES header" to store that information,
which icarus preserves after import as `ines.rom`.
- `save.ram`:
Games that include a save feature
will create this file.
Note that it is only written to disk
when higan exits gracefully;
if higan crashes or is forced to quit,
in-game saves may be lost.
Other emulators sometimes call this an "SRAM file",
even though the same filename is used
with games that included EEPROM or Flash storage,
not just battery-backed Static RAM.
- `rtc.ram`:
Games that include a calendar or real-time clock
will create this file.
- `*.data.rom`, `*.program.rom`:
Files named like this are usually [co-processor firmware][firmware].
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 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#cheat-editor)
is stored here.
- `notes.txt`:
Everything entered in the [Game Notes] is stored here.
- `states/quick/slot-*.bst`:
All [Quick States](save-states.md#quick-states) are stored here.
- `states/managed/slot-*.bst`:
All [Manager States](save-states.md#manager-states) are stored here.
[Game Notes]: ../interface/higan-tools.md#game-notes
The game library
is the folder where all the
[game folders](game-folders.md) go.
When [icarus](../interface/icarus.md) imports a game,
it creates or updates
the corresponding game folder in the game library.
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.
Inside the game library folder
there is a sub-folder for each system.
Inside each system folder
are the game folders
for each imported game.
Why a game library?
-------------------
higan [requires game folders](game-folders.md#why-game-folders),
but it also invented game folders,
so existing games need
to be converted to game folder format
before higan can play them.
The converted copy of a game needs to go *somewhere*.
Also,
for people who have a huge collection of games,
the game library only lists the games they actually play,
rather than every possible game,
making it easier to find the games they like.
Where is the game library?
--------------------------
In Windows,
the default location of
the game library is the `Emulation` folder
inside your profile folder
(To find your profile folder,
press `Win+R` to open the Run dialog,
then type `%USERPROFILE%` and press Enter).
In Linux,
the default location of
the game library is the `Emulation` directory
inside your home directory.
On all platforms,
the game library location can be configured.
See [Moving the Game Library](#moving-the-game-library)
below.
Moving the game library
-----------------------
Moving the game library is a little complicated,
because there are two parts to it:
telling icarus where to put imported games,
and telling higan where to find them.
1. Move your existing game library folder
to the new location,
or otherwise create the folder you want higan to use
as its game library.
1. Launch icarus,
then click the "Settings ..." button in the lower-right,
to open
[the Settings dialog][icsettings].
1. Click the "Change ..." button on the right.
A [filesystem browser][fsbrowser] window will appear,
allowing you to choose
where imported games will be stored.
1. Launch higan,
then from [the Settings menu][settingsmenu],
choose "Advanced ..."
to open [higan's Advanced settings][advsettings].
1. Click the "Change ..." button on the right.
A [filesystem browser][fsbrowser] will appear,
allowing you to choose the same folder again.
[icsettings]: ../interface/icarus.md#the-icarus-settings-dialog
[fsbrowser]: ../interface/common.md#the-filesystem-browser
[settingsmenu]: ../interface/higan.md#the-settings-menu
[advsettings]: ../interface/higan-settings.md#advanced
If a [game folder](game-folders.md) is
the emulation equivalent of
a physical game cartridge,
a manifest is like
the circuit board inside the cartridge:
it connects all the other parts together
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#manifest-viewer).
Why manifests?
--------------
For most consoles,
a manifest isn't strictly necessary:
the raw game data provides enough clues
for emulators to guess the correct circuit board configuration,
or at least
to guess a *reasonable* configuration.
However,
relying on such heuristics often leads to problems:
- Inventing heuristics
that correctly guess the configuration
for a particular game is very difficult.
- If you change the rules,
you really need to re-test
the console's entire game library
to check you haven't broken anything.
- Some games accidentally do the wrong thing.
- The Mega Drive game *Warrior of Rome II*
follows the rule for a European game running at 50fps,
when it's really an American game designed for 60fps.
- Some games deliberately do the wrong thing.
- The Game Boy Advance game *Top Gun - Combat Zones*
follows the rule for
(several kinds of)
save-game storage.
If it detects any save-game storage,
it assumes it's running in an emulator
and disables all the main menu options.
- Heuristics are difficult to reason about.
- If a homebrew developer
takes a game that almost does what they want
and changes it slightly,
it may cause the emulator
to do something completely different
because the modified game
is now a closer match to some other game.
- Heuristics can make sensible configurations impossible.
- If a homebrew developer wants
a particular hardware configuration
that no official games happened to use,
it may not be possible
to trigger it heuristically.
- It's not hardware accurate.
- The original console did not use heuristics
to guess a hardware configuration,
it just used the actual configuration
of the actual hardware.
Manifests provide a way to describe
*exactly* what hardware configuration to use,
no guessing required,
avoiding all these problems entirely.
Where do manifests come from?
-----------------------------
Ideally,
everybody who extracts the data from a game cartridge would
also record the board configuration in a manifest file.
Unfortunately,
manifests were invented long after cartridge extracting,
so there are a lot of previously extracted games
with no manifest attached.
If a game doesn't come with a manifest,
it may be possible to look up the correct manifest.
The
[SNES Preservation Project](https://preservation.byuu.org/)
intends to re-dump every Super Famicom game
and record its board configuration at the same time.
Given a game's data,
you can take the SHA256 fingerprint
and look it up in the Project's database
to find the correct manifest to use.
Unfortunately,
this doesn't help for any other console.
Even for the Super Famicom,
there will always be games
too rare to acquire for re-dumping,
and homebrew that was never on a physical cartridge to begin with.
For these games,
heuristics will always be needed as a fallback,
but at least if the heuristics are wrong
they can be overridden.
If you are a homebrew author
or have dumped a previously-unknown cartridge,
and want to write a manifest yourself,
you should read the [official manifest specification][manifest].
[manifest]: https://doc.byuu.org/higan/manifests/
Ignoring manifests
------------------
Occasionally,
a newly-dumped game will turn out to have
a configuration that can't be expressed
in the existing manifest file format,
and a new format must be designed.
If manifests were always written inside game folders,
games with old-format manifests
would break when played in emulators that supported the new format.
Therefore,
icarus [defaults](../interface/icarus.md#the-icarus-settings-dialog)
to not writing out manifests when it imports games,
and higan [defaults](../interface/higan-settings.md#advanced)
to ignoring manifests that are present.
Instead,
when higan loads a game,
it will ask icarus to generate a temporary manifest in the latest format,
based on the files present in the game folder
and how they are likely to go together.
If the manifest that icarus generates
for some particular game
is broken or buggy,
you'll need to switch the manifest machinery back on
so you can fix it:
- Turn on "Create manifests" in icarus' settings
- Re-import the game in question
to store the broken manifest
as `manifest.bml` in the game folder.
- Edit `manifest.bml` as you see fit
- Turn off "Ignore manifests" in higan's settings
- Load the game in higan to check that your changes fixed the problem
If the manifest format changes in the future,
you'll have to repeat this process
to create a fixed manifest in the new format.
A real game console
is a complex piece of hardware,
with electricity flowing through it
in complex patterns that can't easily
be paused or recorded.
However,
an emulated console is pure software:
it only changes when the emulation software
deliberately updates it,
so the emulator software can save
the entire state of the emulated console
to disk,
and weeks or months later
bring it back to life
as though nothing had ever happened.
Save states versus in-game saves
--------------------------------
Some games include their own systems
for saving and restoring the player's progress.
Here are some of the differences
between save states and in-game saves:
<table>
<thead>
<tr>
<th>Save states</th>
<th>In-game saves</th>
</tr>
</thead>
<tbody>
<tr>
<td>
Work exactly the same way
in every game
</td>
<td>
Works differently in different games,
some games don't support it at all
</td>
</tr>
<tr>
<td>
Save at any time,
anywhere in the game
</td>
<td>
Save only at special save-points
</td>
</tr>
<tr>
<td>
Loading a save
puts the game back exactly how it was
when you pressed save
</td>
<td>
Loading a save
restores some things
(like the player's inventory
or remaining lives),
but may
forget others
(like taking you back to the beginning of the level)
</td>
</tr>
<tr>
<td>
You can have dozens of save states
</td>
<td>
Most games limit you to about 3 saves
</td>
</tr>
<tr>
<td>
Can only be loaded
by the same version of the same emulator
that created it
</td>
<td>
Works with any version of any emulator,
can sometimes even be copied to or from physical cartridges
</td>
</tr>
</tbody>
</table>
**Note:**
Loading a save state
will reset the entire emulated console
to the way it was when the save state was created,
*including in-game saves*.
If you create a save state,
then make an in-game save,
then load the save state,
**your in-game save will be lost**.
Don't do that.
Quick states
------------
higan has five Quick State slots,
which can be used from
[the Tools menu](../interface/higan.md#the-tools-menu),
or with the appropriate
[hotkeys](../interface/higan-settings.md#hotkeys).
Quick states are useful
as extra checkpoints
in games whose checkpoints are too far apart,
or in games that don't have checkpoints at all.
Map the "Save Quick State" and "Load Quick State" hotkeys
to your controller,
and you can cheese your way through just about anything.
Manager states
--------------
higan's
[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.
Manager States are more cumbersome to use than Quick States,
since they cannot be accessed with hotkeys,
but are useful when you want quick access
to many different parts of a game.
higan's original author:
- byuu
We'd like to acknowledge
many invaluable contributions made to higan
by the following individuals:
- Andreas Naive
- Ange Albertini
- anomie
- AWJ
- Bisqwit
- blargg
- Łukasz Krawczyk
- Cydrak
- Danish
- DMV27
- Dr. Decapitator
- endrift
- Fatbag
- FitzRoy
- gekkio
- GIGO
- Hendricks266
- hex_usr
- ikari_01
- jchadwick
- Jonas Quinn
- kode54
- krom
- Lioncash
- Lord Nightmare
- lowkey
- MerryMage
- Matthew Callis
- mightymo
- Nach
- ncbncb
- neviksti
- OV2
- Overload
- p4plus2
- quequotion
- RedDwarf
- Richard Bannister
- Ryphecha
- segher
- Sintendo
- SuperMikeMan
- tetsuo55
- TmEE
- TRAC
- wareya
- zones
It's been a long, wild ride...
apologies to anyone we've missed!
For more information,
see the [credits thread](
https://helmet.kafuka.org/byuubackup2/[email protected]=4&t=1631.html)
on the archive of the official forums.
I see "tearing" when a game scrolls. How can I enable vsync?
------------------------------------------------------------
higan supports synchronising video output
to the display's vertical-synchronisation (or "vsync") signal,
but the option is hidden
because it often causes more problems than it solves
(see the next question).
To enable video synchronisation:
- Open higan's configuration file, `settings.bml`
- On Windows, look in `%LOCALAPPDATA%\higan`
or beside `higan.exe`
- On Linux, look in `~/.local/share/higan`
- Open it in your favourite text editor
(Windows Notepad will corrupt the file,
use WordPad if you don't have anything better)
- Find the line that says "Video"
- Somewhere below that, find an indented line
that says "Synchronize:false".
- Change "false" to "true"
- Save your changes to `settings.bml`
and restart higan
Why is video synchronisation a problem for higan?
-------------------------------------------------
**The short version:**
Turning on video synchronisation
cleans up video tearing,
turning on audio synchronisation
cleans up audio glitches,
but turning on both