ShuriZma
/
bsnes
mirror of https://github.com/bsnes-emu/bsnes.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Finally finished reviewing and polishing all the text!

This commit is contained in:
Tim Allen 2017-08-29 17:22:11 +10:00
parent fab830f84b
commit d8a8f06c35
8 changed files with 114 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
docs/concepts/game-folders.md
View File

@ -2,22 +2,8 @@ A game folder
is higan's way of grouping all
the information and resources required
to properly emulate a particular game.
Other emulators group resources related to a game
by requiring that every file has the 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`:
```text
+- Super Famicom
|
+- dkc3.sfc
|
+- dkc3.srm
```
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`:
@ -32,14 +18,30 @@ and the save data as `save.ram`:
+- 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`:
```text
+- Super Famicom
|
+- dkc3.sfc
|
+- dkc3.srm
```
Why game folders?
-----------------
The traditional files-with-different-extensions system
works well enough when a game only requires
a small number of files,
because a file extension doesn't offer
much room for description.
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,
@ -47,22 +49,23 @@ it also means a game can't use
two or more files in the same format.
Compared to other emulators,
higan tends to use a larger number of files per game.
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 support][msu1]
requires up to 99 audio tracks per game,
supports up to 99 audio tracks per game,
and higan supports up to 133 save-states per game.
Therefore,
Thus,
higan suffers from the limitations of name-based-grouping
more than most.
higan's game folders allow all a game's resources
to be given unique, descriptive filenames,
and to use the file-extension
that's most appropriate for that file.
They also allow emulator-specific data
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.
@ -78,12 +81,11 @@ see [Game Paks on the higan website][gp].
What's in a game folder?
------------------------
As mentioned above,
a game folder collects all the information relevant
A game folder collects all the information relevant
to emulating a particular game.
Not all of the following files
are relevant to every emulated console,
or to every game on a given console,
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
@ -114,12 +116,12 @@ to all emulators that support them:
Games that include a save feature
will create this file.
Note that it is only written to disk
when higan exits gracefully,
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
for cartridges that use EEPROM or Flash storage,
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

4
docs/concepts/game-library.md
View File

@ -4,10 +4,10 @@ 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 menu items
When you use the console submenu items
in [higan's Library menu](../interface/higan.md#the-library-menu),
it higan shows you the games for that console
already in the library.
that are already in the library.
Inside the game library folder
there is a subfolder for each system.

51
docs/concepts/manifests.md
View File

@ -3,8 +3,8 @@ the emulation equivalent of
a physical game cartridge,
a manifest is like
the circuit board inside the cartridge:
it controls how all the other parts of the cartridge
talk to one another and to the console itself.
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
@ -14,15 +14,14 @@ and choosing [Manifest Viewer](../interface/higan-tools.md#the-manifest-viewer).
Why manifests?
--------------
Any given console might support
hundreds or thousands of different games,
but the vast majority of those games
use one of a few different circuit boards.
For most consoles,
a manifest isn't strictly necessary:
the raw game data provides enough clues
to guess a circuit board configuration
that will get the game running,
but relying on heuristics often leads to problems:
for emulators to guess the 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
@ -47,10 +46,10 @@ but relying on heuristics often leads to problems:
- If a homebrew developer
takes a game that almost does what they want
and changes it slightly,
it can result in the emulator
doing something completely different
because it now matches
some completely different game.
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
@ -63,8 +62,9 @@ but relying on heuristics often leads to problems:
it just used the actual configuration
of the actual hardware.
Manifests provide a way to *tell* the emulator
what hardware configuration to use,
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?
@ -72,8 +72,7 @@ Where do manifests come from?
Ideally,
everybody who extracts the data from a game cartridge would
(at the same time)
record the board configuration in a manifest file.
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
@ -95,7 +94,7 @@ 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 cartridge to begin with.
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
@ -128,12 +127,16 @@ 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 the problem:
so you can fix it:
- Turn "Create manifests" back on in icarus' settings
- Re-import the game in question,
- 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`
- Turn "Ignore manifests" off in higan's settings
- Load the game in higan to check that your edit fixed the problem
- 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.

4
docs/concepts/save-states.md
View File

@ -109,8 +109,8 @@ or with the appropriate
Quick states are useful
as extra checkpoints
in games that don't have them,
or where they aren't close enough together.
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.

45
docs/faq.md
View File

@ -6,10 +6,9 @@ to the display's vertical-synchronization (or "vsync") signal,
but the option is hidden
because it often causes more problems than it solves
(see the next question).
To enable video synchronization:
- Open the higan's configuration file, `settings.bml`
- Open higan's configuration file, `settings.bml`
- On Windows, look in `%LOCALAPPDATA%\higan`
or beside `higan.exe`
- On Linux, look in `~/.local/share/higan`
@ -50,8 +49,8 @@ the emulated console's refresh rate:
- The Super Famicom usually runs a little faster than 60Hz
- the PAL variants of most consoles run at 50Hz
- the WonderSwan runs at 75Hz
- While the Game Boy does run its LCD at 60Hz
it can turn it off and on at any time,
- While the Game Boy does run its LCD at 60Hz,
games can turn the LCD off and on at any time,
requiring emulation to pause
until it can get back in sync
with the computer display.
@ -120,7 +119,7 @@ requires an Intel Ivy Bridge (or equivalent),
full-speed for the wireframe animations in Mega Man X2
requires an even faster computer.
Low-power CPUs like ARM chips,
or Intel Atom and Celeron CPUS
or Intel Atom and Celeron CPUs
generally aren't fast enough to emulate the Super Famicom with higan,
although other emulated consoles may work.
@ -168,11 +167,11 @@ Games can and do depend on timing details like
it will interrupt the CPU at exactly the right time
for the CPU to fiddle with the video chip".
higan is therefore very cautious about timing:
while it's emulating the audio chip (for example),
at every point the emulated CPU *might* interrupt
the emulated audio chip,
higan switches to emulating the CPU up to the same point
to find out whether the CPU *will* interrupt it.
while it's emulating the CPU (for example),
at every point the emulated audio chip *might* interrupt
the emulated CPU,
higan switches to emulating the audio chip up to the same point
to find out whether it *will* interrupt the CPU.
In this way,
higan is a little bit like
@ -180,8 +179,8 @@ an office-worker trying to do the jobs of three other people
by running from desk to desk,
sending the same emails
that those three people would send to each other,
leaving themselves a note at each desk to remind themselves
where they were up to when they come back.
leaving itself a note at each desk to remind it
where it was up to when it comes back.
Although this constant switching
is slow and inefficient,
higan does it
@ -224,8 +223,8 @@ Why can't higan use multiple CPU cores?
These days,
most computers contain multiple CPU cores,
allowing them to run different programs,
or different parts of the same program
allowing them to run different programs
(or different parts of the same program)
at the same time.
Since higan requires high CPU performance,
sometimes people suggest that it should split its work
@ -257,26 +256,28 @@ do their work in exactly the same amount of time
as their hardware counterparts.
The problem is forty years of technology
designed to make programs run as fast as possible:
optimizing compilers and superscalar, out-of-order CPU architectures
optimizing compilers
and superscalar, out-of-order CPU architectures
change programs to make them faster,
speeding up some programs more than others
in ways that are very difficult to understand and predict.
Even if higan's emulated devices
ran at the exact, correct speed
on one particular computer,
they'd still run differently on any other computer,
or with a smarter compiler,
or with a smarter CPU.
they'd still run differently on
a computer with a smarter CPU,
or when compiled with a smarter compiler.
Since higan needs its emulated components
to run at particular speeds,
and they won't run at those speeds naturally,
and it's not practical
to make them run at those speeds naturally,
it must force them manually.
An emulated device runs for a little while,
then all the others are run until they catch up.
It's this careful management,
regular stopping and starting,
that makes higan slow,
not the actual emulation of each device,
and so it doesn't make sense
for higan to be multi-threaded.
not the actual emulation of each device.
Having multiple CPU cores waiting on each other
would not help them wait any faster.

21
docs/guides/drivers.md
View File

@ -1,9 +1,8 @@
Unfortunately,
there's no standard for
there's no cross-platform standard for
displaying video,
playing audio,
and accepting input from game controllers
that works on every operating system.
and accepting input from game controllers.
Or rather,
there's many standards,
and different ones work best
@ -20,7 +19,7 @@ of the Settings window.
Here are the most notable drivers
for each platform
for each category.
in each category.
If your copy of higan
includes a driver not listed here,
it's probably a reasonable choice,
@ -44,11 +43,11 @@ Video
On Windows:
- **OpenGL** is usually the best choice,
since it supports [custom shaders](shaders.md),
however it does require support for OpenGL 3.2
which excludes some integrated graphics chipsets
and old graphics cards.
- **OpenGL** is the best choice,
since it's fast
and it supports [custom shaders](shaders.md),
but requires support for OpenGL 3.2.
This excludes some older and weaker hardware.
- **Direct3D** is a good choice
if OpenGL is unavailable.
It also allows
@ -62,7 +61,7 @@ On Linux:
- **OpenGL** is the best choice,
since it's fast
and it supports [custom shaders](shaders.md),
but requires OpenGL 3.2.
but requires support for OpenGL 3.2.
You can check what version of OpenGL
your system supports by running
`glxinfo | grep 'core profile version'`
@ -82,7 +81,7 @@ On Windows:
- **ASIO** offers the lowest possible latency,
but is the least likely to work on any given computer.
- **WASAPI** offers low latency,
but is only slightly more likely to work.
but is only slightly more likely to work than ASIO.
It also offers
[Exclusive Mode](../interface/higan-settings.md#audio),
which can improve audio quality and lower latency,

4
docs/guides/import.md
View File

@ -219,8 +219,8 @@ and one that uses the DSP1B,
so if it cannot find your game in its manifest database,
it will assume it uses DSP1B.
Many games work just as well with either variant,
but Pilotwings requires the DSP1 firmware,
while Ballz 3D requires the DSP1B.
but *Pilotwings* requires the DSP1 firmware,
while *Ballz 3D* requires the DSP1B.
If you try to import a game
using the "Import ROM Files ..." option

33
docs/notes.md
View File

@ -1,24 +1,21 @@
The consoles that higan emulates
are similar in many ways,
but some of them do have particular quirks
that you should be aware of.
but some of them do have particular quirks of their own.
Music and Sound Effect Volume on the Mega Drive
-----------------------------------------------
The Mega Drive has two different audio-generating chips:
- the SN76489 or "PSG" chip,
- the SN76489 or "PSG" chip
inherited from the Master System,
mostly used for sound-effects
like Sonic picking up rings
- the YM2612 or "FM" chip,
mostly used for music
With two different sound sources,
it's important that they have similar volumes,
or the sound-effects will drown out the music,
or vice-versa.
it's important that they have similar volumes
or one kind of sound will drown out the other.
Sega did *not* do this,
and different hardware revisions
used different relative volumes.
@ -26,8 +23,8 @@ used different relative volumes.
higan currently
sets the PSG volume to [125% of the FM volume][vol],
based on [a Sega Genesis model 1 VA6][va6] that byuu owns.
If you feel sound-effects in higan's Mega Drive core
are too loud or too quiet,
If you feel sound-effects in higan's Mega Drive emulation
are too loud or too quiet compared to the music,
you may be comparing it
to a Mega Drive calibrated to a different scale
(or to an emulator tweaked to match such a Mega Drive).
@ -50,7 +47,7 @@ Games that required
the extra hardware in the Game Boy Color
came in transparent cartridges,
and had a slightly different shape
to prevent them from being used in original Game Boys..
to prevent them from being used in original Game Boys.
ROM files for these games
typically have filenames ending in `.gbc`.
@ -117,17 +114,9 @@ higan must guess which storage type to use
and sometimes it guesses incorrectly.
If higan guesses incorrectly for a game you want to play,
you will need to turn on
"Create manifests" in
[the Icarus settings dialog](interface/icarus.md#the-icarus-settings-dialog),
turn off
"Ignore manifests" in
[higan's Advanced settings](interface/higan-settings.md#advanced),
re-import the game,
and edit `manifest.bml` in
[the game folder](concepts/game-folders.md)
to describe the correct storage type.
Try importing other GBA games to see what save types they use.
you will need to override the automatically-generated manifest.
See [Ignoring manifests](concepts/manifests.md#ignoring-manifests)
for details.
For more discussion of the GBA save type mess,
see [What's the deal with... GBA save files?][gbasaves]
@ -145,7 +134,7 @@ included a rumble motor within the cartridge itself.
Because higan does not currently support
game-specific controller features,
to experience the rumble effect in higan
you'll need to configure the console itself:
you'll need to configure the console:
- Open
[higan's Input settings](interface/higan-settings.md#input)