Emulation/Mesen
1
0
Fork 0
mirror of https://github.com/SourMesen/Mesen.git synced 2024-06-02 19:38:32 -04:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Added source for the online documentation site

Browse source
This commit is contained in:
Sour 2018-03-04 20:31:33 -05:00
parent ba7fd71746
commit 23c85a447b
202 changed files with 15580 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.gitignore vendored
View file

@ -169,3 +169,6 @@ $RECYCLE.BIN/
*.VC.db
*.VC.db-wal
*.VC.db-shm
Docs/public/
Docs/*.exe

5
Docs/README.md Normal file
View file

@ -0,0 +1,5 @@
This is the source code/resources used to build the documentation website located at [https://www.mesen.ca/docs/](https://www.mesen.ca/docs/)
It requires hugo to build. You can download hugo here: [https://gohugo.io/](https://gohugo.io/).
Use the "build.cmd" batch file to build a copy of the documentation - it will be saved to the "public" subfolder.

4
Docs/build.cmd Normal file
View file

@ -0,0 +1,4 @@
hugo
del public\js\searchjson.js
echo var searchjson = >>public\js\searchjson.js
type public\index.json>>public\js\searchjson.js

24
Docs/config.toml Normal file
View file

@ -0,0 +1,24 @@
baseURL = ""
relativeURLS = true
uglyURLs = true
languageCode = "en-us"
title = "Mesen Documentation"
theme = "learn"
[outputs]
home = [ "HTML", "RSS", "JSON"]
[params]
themeVariant = "green"
[[menu.shortcuts]]
name = "<img style='vertical-align: middle' src='/images/favicon.png'/> <span style='display: inline;vertical-align: middle'>Website</span>"
identifier = "website"
url = "https://www.mesen.ca"
weight = 9
[[menu.shortcuts]]
name = "<i class='fa fa-github'></i> GitHub"
identifier = "github"
url = "https://github.com/SourMesen/Mesen"
weight = 10

35
Docs/content/_index.md Normal file
View file

@ -0,0 +1,35 @@
---
title: Home
weight: 1
chapter: false
toc: false
---
<h1>Mesen - NES/Famicom Emulator</h1>
### Table of contents ###
1. [Getting Started](/gettingstarted.html)
2. [Configuration](/configuration.html)
* [Audio Options](/configuration/audio.html)
* [Input Options](/configuration/input.html)
* [Video Options](/configuration/video.html)
* [Emulation Options](/configuration/emulation.html)
* [Preferences](/configuration/preferences.html)
3. [Tools](/tools.html)
* [Netplay](/tools.html#netplay)
* [Movies](/tools.html#movies)
* [Cheats](/tools.html#cheats)
* [Sound Recorder](/tools.html#sound-recorder)
* [Video Recorder](/tools.html#video-recorder)
* [Log Window](/tools.html#log-window)
4. [Debugging Tools](/debugging.html)
* [Debugger](/debugging/debugger.html)
* [PPU Viewer](/debugging/ppuviewer.html)
* [Memory Tools](/debugging/memorytools.html)
* [Trace Logger](/debugging/tracelogger.html)
* [Assembler](/debugging/assembler.html)
* [Script Window](/debugging/scriptwindow.html)
* [Integration with CC65/ASM6](/debugging/debuggerintegration.html)
5. [HD Packs](/hdpacks.html)
6. [Lua API reference](/apireference.html)

90
Docs/content/apireference/Callbacks.md Normal file
View file

@ -0,0 +1,90 @@
---
title: Callbacks
weight: 5
pre: ""
chapter: false
---
## addEventCallback ##
**Syntax**
emu.addEventCallback(function, type)
**Parameters**
function - A Lua function.
type - *Enum* See [eventType](/apireference/enums.html#eventtype).
**Return value**
Returns an integer value that can be used to remove the callback by calling [removeEventCallback](#removeeventcallback).
**Description**
Registers a callback function to be called whenever the specified event occurs.
The callback function receives no parameters.
## removeEventCallback ##
**Syntax**
emu.removeEventCallback(reference, type)
**Parameters**
reference - The value returned by the call to [addEventCallback](#addeventcallback).
type - *Enum* See [eventType](/apireference/enums.html#eventtype).
**Return value**
*None*
**Description**
Removes a previously registered callback function.
## addMemoryCallback ##
**Syntax**
emu.addMemoryCallback(function, type, startAddress, endAddress)
**Parameters**
function - A Lua function.
type - *Enum* See [memCallbackType](/apireference/enums.html#memcallbacktype)
startAddress - *Integer* Start of the CPU memory address range to register the callback on.
endAddress - *Integer* End of the CPU memory address range to register the callback on.
**Return value**
Returns an integer value that can be used to remove the callback by calling [removeMemoryCallback](#removememorycallback).
**Description**
Registers a callback function to be called whenever the specified event occurs.
The callback function receives 2 parameters `address` and `value` that correspond to the address being written to or read from, and the value that is being read/written.
For reads, the callback is called *after* the read is performed.
For writes, the callback is called *before* the write is performed.
If the callback returns an integer value, it will replace the value -- you can alter the results of read/write operation using this. e.g:
```lua
function writeCallback(address, value)
--This sets bit 0 to 0 for all CHR RAM writes
return value & 0xFE
end
emu.addMemoryCallback(writeCallback, emu.memCallbackType.ppuWrite, 0, 0x1FFF)
```
## removeMemoryCallback ##
**Syntax**
emu.removeMemoryCallback(reference, type, startAddress, endAddress)
**Parameters**
reference - The value returned by the call to [addMemoryCallback](#addmemorycallback).
type - *Enum* See [memCallbackType](/apireference/enums.html#memcallbacktype).
startAddress - *Integer* Start of the CPU memory address range to unregister the callback from.
endAddress - *Integer* End of the CPU memory address range to unregister the callback from.
**Return value**
*None*
**Description**
Removes a previously registered callback function.

27
Docs/content/apireference/Changelog.md Normal file
View file

@ -0,0 +1,27 @@
---
title: Changelog
weight: 1
pre: ""
chapter: false
---
## Changes between 0.9.3 and 0.9.4 ##
### New features ###
* New functions:
* **<kbd>[getLogWindowLog](/apireference/misc.html#getlogwindowlog)</kbd>**
* **<kbd>[getRomInfo](/apireference/misc.html#getrominfo)</kbd>**
* **<kbd>[getScriptDataFolder](/apireference/misc.html#getscriptdatafolder)</kbd>**
* **<kbd>[isKeyPressed](/apireference/input.html#iskeypressed)</kbd>**
* **<kbd>[clearSavestateData](/apireference/misc.html#clearsavestatedata)</kbd>**
* **<kbd>[getSavestateData](/apireference/misc.html#getsavestatedata)</kbd>**
* **<kbd>[loadSavestateAsync](/apireference/misc.html#loadsavestateasync)</kbd>**
* **<kbd>[saveSavestateAsync](/apireference/misc.html#savesavestateasync)</kbd>**
* New event callbacks: [**<kbd>inputPolled</kbd>**, **<kbd>stateLoaded</kbd>**, **<kbd>stateSaved</kbd>**](/apireference/enums.html#eventtype)
* New memory types: [**<kbd>cpuDebug</kbd>**, **<kbd>ppuDebug</kbd>**](/apireference/enums.html#memtype)
### Breaking changes ###
* Removed the **<kbd>debugRead</kbd>**, **<kbd>debugReadWord</kbd>**, **<kbd>debugWrite</kbd>** and **<kbd>debugWriteWord</kbd>** functions. They have been replaced by the [memType.cpuDebug](/apireference/enums.html#memtype) and [memType.ppuDebug](/apireference/enums.html#memtype) enum values.
* The behavior of the **<kbd>[setInput](/apireference/input.html#setinput)</kbd>** function has changed.
* The return values for the APU portion of the **<kbd>[getState](/apireference/emulation.html#getstate)</kbd>** function has slightly changed.

135
Docs/content/apireference/Drawing.md Normal file
View file

@ -0,0 +1,135 @@
---
title: Drawing
weight: 10
pre: ""
chapter: false
---
## Drawing basics ##
All drawing-related functions share a few properties:
- (x, y) coordinates must be between (0, 0) and (255, 239)
- The "duration" is specified as a number of frames during which the drawing must remain on the screen. This defaults to 1 frame when unspecified, and draw calls will be permanent (until a call to [clearScreen](#clearscreen)) if duration is set to 0.
- Colors are integers in ARGB format:
White: 0xFFFFFF
Black: 0x000000
Red: 0xFF0000
Green: 0x00FF00
Blue: 0x0000FF
The alpha component (transparency) can be used and defaults to being fully opaque when set to 0 or omitted. (0xFF is fully transparent)
e.g:
semi-transparent black: 0x7F000000
opaque gray: 0xFF888888 (fully transparent gray color)
## drawPixel ##
**Syntax**
emu.drawPixel(x, y, color, duration)
**Parameters**
x - *Integer* X position
y - *Integer* Y position
color - *Integer* Color
duration - *Integer* Number of frames to display (Default: 1 frame)
**Return value**
*None*
**Description**
Draws a pixel at the specified (x, y) coordinates using the specified color for a specific number of frames.
## drawLine ##
**Syntax**
emu.drawLine(x, y, x2, y2, color, duration)
**Parameters**
x - *Integer* X position (start of line)
y - *Integer* Y position (start of line)
x2 - *Integer* X position (end of line)
y2 - *Integer* Y position (end of line)
color - *Integer* Color
duration - *Integer* Number of frames to display (Default: 1 frame)
**Return value**
*None*
**Description**
Draws a line between (x, y) to (x2, y2) using the specified color for a specific number of frames.
## drawRectangle ##
**Syntax**
emu.drawRectangle(x, y, width, height, color, fill, duration)
**Parameters**
x - *Integer* X position
y - *Integer* Y position
width - *Integer* The rectangle's width
height - *Integer* The rectangle's height
color - *Integer* Color
fill - *Boolean* Whether or not to draw an outline, or a filled rectangle.
duration - *Integer* Number of frames to display (Default: 1 frame)
**Return value**
*None*
**Description**
Draws a rectangle between (x, y) to (x+width, y+height) using the specified color for a specific number of frames.
If *fill* is false, only the rectangle's outline will be drawn.
## drawString ##
**Syntax**
emu.drawString(x, y, text, textColor, backgroundColor, duration)
**Parameters**
x - *Integer* X position
y - *Integer* Y position
text- *String* The text to display
textColor - *Integer* Color to use for the text
backgroundColor - *Integer* Color to use for the text's background color
duration - *Integer* Number of frames to display (Default: 1 frame)
**Return value**
*None*
**Description**
Draws text at (x, y) using the specified text and colors for a specific number of frames.
## clearScreen ##
**Syntax**
emu.clearScreen()
**Return value**
*None*
**Description**
Removes all drawings from the screen.
## getPixel ##
**Syntax**
emu.getPixel(x, y)
**Parameters**
x - *Integer* X position
y - *Integer* Y position
**Return value**
*Integer* ARGB color
**Description**
Returns the color (in ARGB format) of the PPU's output for the specified location.

266
Docs/content/apireference/Emulation.md Normal file
View file

@ -0,0 +1,266 @@
---
title: Emulation
weight: 15
pre: ""
chapter: false
---
## getState ##
**Syntax**
emu.getState()
**Return value**
*Table* Current emulation state with the following structure:
region: int,
clockRate: int,
cpu: {
status: int,
a: int,
irqFlag: int,
cycleCount: int,
pc: int,
y: int,
x: int,
sp: int,
nmiFlag: bool
},
ppu: {
cycle: int,
scanline: int,
frameCount: int,
control: {
backgroundEnabled: bool,
intensifyBlue: bool,
intensifyRed: bool,
backgroundPatternAddr: int,
grayscale: bool,
verticalWrite: bool,
intensifyGreen: bool,
nmiOnVBlank: bool,
spritesEnabled: bool,
spritePatternAddr: int,
spriteMask: bool,
largeSprites: bool,
backgroundMask: bool
},
status: {,
spriteOverflow: bool,
verticalBlank: bool,
sprite0Hit: bool
},
state: {
status: int,
lowBitShift: int,
xScroll: int,
highBitShift: int,
videoRamAddr: int,
control: int,
mask: int,
tmpVideoRamAddr: int,
writeToggle: bool,
spriteRamAddr: int
}
},
apu: {
square1: {
outputVolume: int,
frequency: float,
duty: int,
period: int,
enabled: bool,
dutyPosition: int,
sweepShift: int,
sweepPeriod: int,
sweepEnabled: bool,
sweepNegate: bool
envelope: {
counter: int,
loop: bool,
divider: int,
volume: int,
startFlag: bool,
constantVolume: bool
},
lengthCounter: {
halt: bool,
counter: int,
reloadValue: int
}
},
square2: {
outputVolume: int,
frequency: float,
duty: int,
period: int,
enabled: bool,
dutyPosition: int,
sweepShift: int,
sweepPeriod: int,
sweepEnabled: bool,
sweepNegate: bool,
envelope: {
counter: int,
loop: bool,
divider: int
volume: int,
startFlag: bool,
constantVolume: bool
},
lengthCounter: {
halt: bool,
counter: int,
reloadValue: int
}
},
triangle: {
outputVolume: int,
frequency: float,
sequencePosition: int,
period: int,
enabled: bool,
lengthCounter: {
halt: bool,
counter: int,
reloadValue: int
}
},
noise: {
modeFlag: bool,
enabled: bool,
outputVolume: int,
frequency: float,
period: int,
shiftRegister: int,
envelope: {
counter: int,
loop: bool,
divider: int,
volume: int,
startFlag: bool,
constantVolume: bool
},
lengthCounter: {
halt: bool,
counter: int,
reloadValue: int
}
},
dmc: {
sampleLength: int,
irqEnabled: bool,
loop: bool,
outputVolume: int,
bytesRemaining: int,
sampleAddr: int,
period: int,
sampleRate: float
},
frameCounter: {
fiveStepMode: int,
irqEnabled: int,
sequencePosition: int
}
},
cart: {
selectedPrgPages: array,
chrRomSize: int,
chrRamSize: int,
prgPageCount: int,
chrPageSize: int,
selectedChrPages: array,
chrPageCount: int,
prgRomSize: int,
prgPageSize: int,
}
**Description**
Return a table containing information about the state of the CPU, PPU, APU and cartridge.
## setState ##
**Syntax**
emu.setState(state)
**Parameters**
state - *Table* A table containing the state of the emulation to apply.
**Return value**
*None*
**Description**
Updates the CPU and PPU's state.
The *state* parameter must be a table in the same format as the one returned by [getState()](#getstate)
**Note:** the state of the APU or cartridge cannot be modified by using setState().
## breakExecution ##
**Syntax**
emu.breakExecution()
**Return value**
*None*
**Description**
Breaks the execution of the game and displays the debugger window.
## execute ##
**Syntax**
emu.execute(count, type)
**Parameters**
count - *Integer* The number of cycles or instructions to run before breaking
type - *Enum* See [executeCountType](/apireference/enums.html#executecounttype)
**Return value**
*None*
**Description**
Runs the emulator for the specified number of cycles/instructions and then breaks the execution.
## reset ##
**Syntax**
emu.reset()
**Return value**
*None*
**Description**
Resets the current game.
## resume ##
**Syntax**
emu.resume()
**Return value**
*None*
**Description**
Resumes execution after breaking.
## rewind ##
**Syntax**
emu.rewind(seconds)
**Parameters**
seconds - *Integer* The number of seconds to rewind
**Return value**
*None*
**Description**
Instantly rewinds the emulation by the number of seconds specified.
**Note:** this can only be called from within a "StartFrame" event callback.

91
Docs/content/apireference/Enums.md Normal file
View file

@ -0,0 +1,91 @@
---
title: Enums
weight: 55
pre: ""
chapter: false
---
## eventType ##
**Syntax**
emu.eventType.[value]
**Values**
```text
reset = 0, Triggered when a soft reset occurs
nmi = 1, Triggered when an nmi occurs
irq = 2, Triggered when an irq occurs
startFrame = 3, Triggered at the start of a frame (cycle 0, scanline -1)
endFrame = 4, Triggered at the end of a frame (cycle 0, scanline 241)
codeBreak = 5, Triggered when code execution breaks (e.g due to a breakpoint, etc.)
stateLoaded = 6, Triggered when a user manually loads a savestate
stateSaved = 7, Triggered when a user manually saves a savestate
inputPolled = 8 Triggered when the emulation core polls the state of the input devices for the next frame
```
**Description**
Used by [addEventCallback](/apireference/callbacks.html#addeventcallback) / [removeEventCallback](/apireference/callbacks.html#removeeventcallback) calls.
## executeCountType ##
**Syntax**
emu.executeCountType.[value]
**Values**
```text
cpuCycles = 0, Count the number of CPU cycles
ppuCycles = 1, Count the number of PPU cycles
cpuInstructions = 2 Count the number of CPU instructions
```
**Description**
Used by [execute](/apireference/emulation.html#execute) calls.
## memCallbackType ##
**Syntax**
emu.memCallbackType.[value]
**Values**
```text
cpuRead = 0, Triggered when a read instruction is executed
cpuWrite = 1, Triggered when a write instruction is executed
cpuExec = 2, Triggered when any memory read occurs due to the CPU's code execution
ppuRead = 3, Triggered when the PPU reads from its memory bus
ppuWrite = 4 Triggered when the PPU writes to its memory bus
```
**Description**
Used by [addMemoryCallback](/apireference/callbacks.html#addmemorycallback) / [removeMemoryCallback](/apireference/callbacks.html#removememorycallback) calls.
## memType ##
**Syntax**
emu.memType.[value]
**Values**
```text
cpu = 0, CPU memory - $0000 to $FFFF Warning: Reading or writing to this memory type may cause side-effects!
ppu = 1, PPU memory - $0000 to $3FFF Warning: Reading or writing to this memory type may cause side-effects!
palette = 2, Palette memory - $00 to $3F
oam = 3, OAM memory - $00 to $FF
secondaryOam = 4, Secondary OAM memory - $00 to $1F
prgRom = 5, PRG ROM - Range varies by game
chrRom = 6, CHR ROM - Range varies by game
chrRam = 7, CHR RAM - Range varies by game
workRam = 8, Work RAM - Range varies by game
saveRam = 9, Save RAM - Range varies by game
cpuDebug = 256, CPU memory - $0000 to $FFFF Same as memType.cpu but does NOT cause any side-effects.
ppuDebug = 257 PPU memory - $0000 to $3FFF Same as memType.ppu but does NOT cause any side-effects.
```
**Description**
Used by [read](/apireference/memoryaccess.html#read-readword) / [write](/apireference/memoryaccess.html#write-writeword) calls.

66
Docs/content/apireference/Input.md Normal file
View file

@ -0,0 +1,66 @@
---
title: Input
weight: 20
pre: ""
chapter: false
---
## getInput ##
**Syntax**
emu.getInput(port)
**Parameters**
port - *Integer* The port number to read (0 to 3)
**Return value**
*Table* A table containing the status of all 8 buttons.
**Description**
Returns a table containing the status of all 8 buttons: { a, b, select, start, up, down, left, right }
## setInput ##
**Syntax**
emu.setInput(port, input)
**Parameters**
port - *Integer* The port number to apply the input to (0 to 3)
input - *Table* A table containing the state of some (or all) of the 8 buttons (same format as returned by [getInput](#getinput))
**Return value**
*None*
**Description**
Buttons enabled or disabled via setInput will keep their state until the next *inputPolled* event.
If a button's value is not specified to either true or false in the *input* argument, then the player retains control of that button. For example, setInput(0, { select = false, start = false}) will prevent the player 1 from using both the start and select buttons, but all other buttons will still work as normal.
To properly control the emulation, it is recommended to use this function within a callback for the *inputPolled* event. Otherwise, the inputs may not be applied before the ROM has the chance to read them.
## getMouseState ##
**Syntax**
emu.getMouseState()
**Return value**
*Table* The mouse's state
**Description**
Returns a table containing the position and the state of all 3 buttons: { x, y, left, middle, right }
## isKeyPressed ##
**Syntax**
emu.isKeyPressed(keyName)
**Parameters**
keyName - *String* The name of the key to check
**Return value**
*Boolean* The key's state (true = pressed)
**Description**
Returns whether or not a specific key is pressed. The "keyName" must be the same as the string shown in the UI when the key is bound to a button.

37
Docs/content/apireference/Logging.md Normal file
View file

@ -0,0 +1,37 @@
---
title: Logging
weight: 25
pre: ""
chapter: false
---
## displayMessage ##
**Syntax**
emu.displayMessage(category, text)
**Parameters**
category - *String* The category is the portion shown between brackets []
text - *String* Text to show on the screen
**Return value**
*None*
**Description**
Displays a message on the main window in the format "[category] text"
## log ##
**Syntax**
emu.log(text)
**Parameters**
text - *String* Text to log
**Return value**
*None*
**Description**
Logs the given string in the script's log window - useful for debugging scripts.

67
Docs/content/apireference/MemoryAccess.md Normal file
View file

@ -0,0 +1,67 @@
---
title: Memory Access
weight: 30
pre: ""
chapter: false
---
## read / readWord ##
**Syntax**
emu.read(address, type, signed = false)
emu.readWord(address, type, signed = false)
**Parameters**
address - *Integer* The address/offset to read from.
type - *Enum* The type of memory to read from. See [memType](/apireference/enums.html#memtype).
signed - (optional) *Boolean* If true, the value returned will be interpreted as a signed value.
**Return value**
An 8-bit (read) or 16-bit (readWord) value.
**Description**
Reads a value from the specified [memory type](/apireference/enums.html#memtype).
When calling read / readWord with the [memType.cpu](/apireference/enums.html#memtype) or [memType.ppu](/apireference/enums.html#memtype) memory types, emulation side-effects may occur.
To avoid triggering side-effects, use the [memType.cpuDebug](/apireference/enums.html#memtype) or [memType.ppuDebug](/apireference/enums.html#memtype) types, which will not cause side-effects.
## write / writeWord ##
**Syntax**
emu.write(address, value, type)
emu.writeWord(address, value, type)
**Parameters**
address - *Integer* The address/offset to write to.
value - *Integer* The value to write.
type - *Enum* The type of memory to write to. See [memType](/apireference/enums.html#memtype).
**Return value**
*None*
**Description**
Writes an 8-bit or 16-bit value to the specified [memory type](/apireference/enums.html#memtype).
Normally read-only types such as PRG-ROM or CHR-ROM can be written to when using [memType.prgRom](/apireference/enums.html#memtype) or [memType.chrRom](/apireference/enums.html#memtype).
Changes will remain in effect until a power cycle occurs.
To revert changes done to ROM, see [revertPrgChrChanges](#revertprgchrchanges).
When calling write / writeWord with the [memType.cpu](/apireference/enums.html#memtype) or [memType.ppu](/apireference/enums.html#memtype) memory types, emulation side-effects may occur.
To avoid triggering side-effects, use the [memType.cpuDebug](/apireference/enums.html#memtype) or [memType.ppuDebug](/apireference/enums.html#memtype) types, which will not cause side-effects.
## revertPrgChrChanges ##
**Syntax**
emu.revertPrgChrChanges()
**Return value**
*None*
**Description**
Reverts all modifications done to PRG-ROM and CHR-ROM via write/writeWord calls.

212
Docs/content/apireference/Misc.md Normal file
View file

@ -0,0 +1,212 @@
---
title: Miscellaneous
weight: 40
pre: ""
chapter: false
---
## Save States ##
There are 2 separate save state APIs.
The first one is synchronous and uses the [saveSavestate](#savesavestate) and [loadSavestate](#loadsavestate) functions. Its main restriction is that it can only be used inside "startFrame" or "cpuExec" callback functions.
The second API is asynchronous and uses an internally-managed "save slot" system to hold states in memory. It uses the following functions: [saveSavestateAsync](#savesavestateasync), [loadSavestateAsync](#loadsavestateasync), [getSavestateData](#getsavestatedata) and [clearSavestateData](#clearsavestatedata).
### saveSavestate ###
**Syntax**
emu.saveSavestate()
**Return value**
*String* A string containing a binary blob representing the emulation's current state.
**Description**
Creates a savestate and returns it as a binary string. (The savestate is not saved on disk)
**Note:** this can only be called from within a "startFrame" event callback or "cpuExec" memory callback.
### saveSavestateAsync ###
**Syntax**
emu.saveSavestateAsync(slotNumber)
**Parameters**
slotNumber - *Integer* A slot number to which the savestate data will be stored (slotNumber must be >= 0)
**Return value**
*None*
**Description**
Queues a save savestate request. As soon at the emulator is able to process the request, it will be saved into the specified slot.
This API is asynchronous because save states can only be taken in-between 2 CPU instructions, not in the middle of an instruction.
When called while the CPU is in-between 2 instructions (e.g: inside the callback of an cpuExec or startFrame event), the save state will be taken immediately and its data will be available via [getSavestateData](#getsavestatedata) right after the call to saveSavestateAsync.
The savestate can be loaded by calling the [loadSavestateAsync](#loadsavestateasync) function.
### loadSavestate ###
**Syntax**
emu.loadSavestate(savestate)
**Parameters**
savestate - *String* A binary blob representing a savestate, as returned by [saveSavestate()](#savesavestate)
**Return value**
*None*
**Description**
Loads the specified savestate.
**Note:** this can only be called from within a "startFrame" event callback or "cpuExec" memory callback.
### loadSavestateAsync ###
**Syntax**
emu.loadSavestateAsync(slotNumber)
**Parameters**
slotNumber - *Integer* The slot number to load the savestate data from (must be a slot number that was used in a preceding [saveSavestateAsync](#savesavestateasync) call)
**Return value**
*Boolean* Returns true if the slot number was valid.
**Description**
Queues a load savestate request. As soon at the emulator is able to process the request, the savestate will be loaded from the specified slot.
This API is asynchronous because save states can only be loaded in-between 2 CPU instructions, not in the middle of an instruction.
When called while the CPU is in-between 2 instructions (e.g: inside the callback of an cpuExec or startFrame event), the savestate will be loaded immediately.
### getSavestateData ###
**Syntax**
emu.getSavestateData(slotNumber)
**Parameters**
slotNumber - *Integer* The slot number to get the savestate data from (must be a slot number that was used in a preceding [saveSavestateAsync](#savesavestateasync) call)
**Return value**
*String* A binary string containing the savestate
**Description**
Returns the savestate stored in the specified savestate slot.
### clearSavestateData ###
**Syntax**
emu.clearSavestateData(slotNumber)
**Parameters**
slotNumber - *Integer* The slot number to get the savestate data from (must be a slot number that was used in a preceding [saveSavestateAsync](#savesavestateasync) call)
**Return value**
*None*
**Description**
Clears the specified savestate slot (any savestate data in that slot will be removed from memory).
## Cheats ##
### addCheat ###
**Syntax**
emu.addCheat(cheatCode)
**Parameters**
cheatCode - *String* A game genie format cheat code.
**Return value**
*None*
**Description**
Activates a game genie cheat code (6 or 8 characters).
**Note:** cheat codes added via this function are not permanent and not visible in the UI.
### clearCheats ###
**Syntax**
emu.clearCheats()
**Return value**
*None*
**Description**
Removes all active cheat codes (has no impact on cheat codes saved within the UI)
## Misc ##
### getLogWindowLog ###
**Syntax**
emu.getLogWindowLog()
**Return value**
*String* A string containing the log shown in the log window
**Description**
Returns the same text as what is shown in the emulator's Log Window.
### getRomInfo ###
**Syntax**
emu.getRomInfo()
**Return value**
*Table* Information about the current ROM with the following structure:
```text
name: string, Filename of the current ROM
path: string, Full path to the current ROM (including parent compressed archive when needed)
fileCrc32Hash: int, The CRC32 value for the whole ROM file
fileSha1Hash: string, The SHA1 hash for the whole ROM file
prgChrCrc32Hash: int, The CRC32 value for the file, excluding its 16-byte header
prgChrMd5Hash: string, The MD5 hash for the file, excluding its 16-byte header
format: int, Value that represents the ROM format: 1 = iNES, 2 = UNIF, 3 = FDS, 4 = NSF
isChrRam: bool true when the game uses CHR RAM, false otherwise
```
**Description**
Returns information about the ROM file that is currently running.
### getScriptDataFolder ###
**Syntax**
emu.getScriptDataFolder()
**Return value**
*String* The script's data folder
**Description**
This function returns the path to a unique folder (based on the script's filename) where the script should store its data (if any data needs to be saved).
The data will be saved in subfolders inside the LuaScriptData folder in Mesen's home folder.
### takeScreenshot ###
**Syntax**
emu.takeScreenshot()
**Return value**
*String* A binary string containing a PNG image.
**Description**
Takes a screenshot and returns a PNG file as a string.
The screenshot is not saved to the disk.

23
Docs/content/apireference/_index.md Normal file
View file

@ -0,0 +1,23 @@
---
title: Lua API reference
weight: 55
chapter: false
toc: false
---
This section documents the Mesen-specific Lua API that is available in scripts via the [script window](/debugging/scriptwindow.html).
## Changelog ##
The Lua is still a recent feature and not completely stable yet. To get a list of the major changes between different versions of Mesen, take a look at the [Changelog](/apireference/changelog.html).
## API References ##
* [Callbacks](/apireference/callbacks.html)
* [Drawing](/apireference/drawing.html)
* [Emulation](/apireference/emulation.html)
* [Input](/apireference/input.html)
* [Logging](/apireference/logging.html)
* [Memory Access](/apireference/memoryaccess.html)
* [Miscellaneous](/apireference/misc.html)
* [Enums](/apireference/enums.html)

41
Docs/content/configuration/Audio.md Normal file
View file

@ -0,0 +1,41 @@
---
title: Audio Options
weight: 2
chapter: false
---
### General Options ###
<div class="imgBox"><div>
<img src="/images/AudioOptions_General.png" />
<span>General Options</span>
</div></div>
**Audio Device**: Selects which device is used for audio output (e.g computer speakers, or a headset)
**Sample Rate**: Selects the sample rate for the audio output -- typically, computers output at 44,100Hz or 48,000Hz, so they usually offer the best sound quality.
**Latency**: This represents the length of the buffer used in audio processing. A smaller value results in less delay between the audio and video, however, depending on the hardware used, a value that is too small may cause sound problems.
In addition, the **volume** and **panning** of each sound channel can be adjusted. For more control over the actual sound, the equalizer can be used to alter the relative strength of specific frequencies -- with work, this can be used to make the audio sound more like an actual NES would.
A number of audio effects are available in the `Effects` tab -- the Stereo Delay effect, in particular, produces a relatively nice fake stereo effect.
<div class="clear"></div>
### Advanced Options ###
<div class="imgBox"><div>
<img src="/images/AudioOptions_Advanced.png" />
<span>Advanced Options</span>
</div></div>
Unlike all the other options before it, the options in this section affect the way the sound is emulated.
* **Mute ultrasonic frequencies on the triangle channel**: This option mutes the triangle channel under certain conditions, which prevents it from causing popping sounds.
* **Reduce popping sounds on the DMC channel**: Similar to the previous option, but for the DMC channel -- this option prevents games from changing the output of the DMC channel too abruptly, which often causes popping sounds.
* **Swap square channel duty cycles**: This option is to mimic some older NES clones that had incorrect sound output for both of the square channels. It greatly alters the sound in some games, and shouldn't be enabled unless you want this behavior.
* **Disable noise channel mode flag**: Very early Famicom models did not implement this feature, so this option is available to mimic early Famicom consoles. It changes the sound output of the noise channel in some games, and shouldn't be enabled unless you want this behavior.

77
Docs/content/configuration/Emulation.md Normal file
View file

@ -0,0 +1,77 @@
---
title: Emulation Options
weight: 8
chapter: false
---
## General Options ##
<div class="imgBox"><div>
<img src="/images/EmulationSettings_General.png" />
<span>General Options</span>
</div></div>
**Emulation Speed**: This configures the regular speed to use when emulating. This should normally be set to `100%`.
**Fast Forward Speed**: This is the alternate speed that is used when the [Fast Forward button](/configuration/preferences.html#shortcut-keys) is held down.
**Rewind Speed**: This configures the speed at which to rewind the gameplay when the [Rewind button](/configuration/preferences.html#shortcut-keys) is held down.
{{% notice tip %}}
Set any speed value to 0 to make Mesen run as fast as it can.
{{% /notice %}}
## Advanced Options ##
{{% notice warning %}}
Several options in this section should NOT be enabled to avoid issues in some games -- they are available here stricly for the sake of completeness (and testing homebrew software, etc.). These options are marked with the `(not recommended)` tag in the UI.
{{% /notice %}}
<div class="imgBox"><div>
<img src="/images/EmulationSettings_Advanced.png" />
<span>Advanced Options</span>
</div></div>
**Remove sprite limit**: The NES can normally only draw up to 8 sprites per line -- this limitation is indirectly responsible for *some* of the flickering seen in games at times. When this option is enabled, the limit is disabled, allowing up to 64 sprites to be drawn on the same line.
**Automatically re-enable sprite limit as needed to prevent graphical glitches when possible**: Some games rely on the sprite limit to hide objects from view. These games will have graphical glitches when the `Remove sprite limit` option is enabled. By enabling this option, Mesen will try to detect when games are attempting to hit the sprite limit on purpose and temporarely re-enable the limit in these specific cases. This option is not perfect and may not work in certain games, but it helps reduce the potential negative impacts of the `Remove sprite limit` option.
**Use NES/HVC-101 (Top-loader / AV Famicom) behavior**: The NES and Famicom both had 2 different releases - their original model and the "top loader" model. Both of these have slightly different behavior when it comes to their input ports. When enabled, this option causes Mesen to simulate the top loader models. No games are known to rely on this behavior.
**Use alternative MMC3 IRQ behavior**: The MMC3 has a number of different variants (A, B and C). By default, Mesen uses the IRQ behavior for versions B and C. By turning this option on, Mesen will default to using the MMC3A's IRQ behavior instead. There is usually no reason to enable this.
**Enable OAM RAM decay**: On all models, OAM RAM decays whenever rendering is disabled. This causes the values in OAM RAM to randomly change, which may cause sprite-related glitches on the screen. No known game relies on this -- the option is offered here mostly for the sake of homebrew software testing.
**Do not reset PPU when resetting console**: On the Famicom and top loader NES, the PPU does not reset when pressing the reset button (only the CPU is reset). When enabled, only the CPU resets when the reset button is pressed.
**Disable PPU $2004 reads**: On some early models, the OAM RAM cannot be read via the $2004 register (in this case, $2004 becomes a write-only register). When enabled, this option emulates this behavior.
**Disable PPU OAMADDR bug emulation**: On some models, a bug occurs that corrupts OAM RAM under certain circumstances. When this option is enabled, the bug is no longer emulated. This bug is required for at least 1 game to work properly.
**Disable PPU palette reads**: On some early models, it is not possible to read the palette RAM via $2007 -- when enabled, this option emulates this behavior, making reads to palette RAM return corresponding values in the PPU's memory instead.
**Allow invalid input**: On a NES controller, it is impossible to press both left and right or up and down at the same time on the controller's D-pad. Some games rely on this and pressing both buttons at once can cause glitches. When enabled, this option makes it possible to press opposite directional buttons at the same time.
**Default power on state for RAM**: On a console, the RAM's state at power on is undetermined and relatively random. This option lets you select Mesen's behavior when initializing RAM - set all bits to 0, set all bits to 1, or randomize the value of each bit.
## Overclocking ##
{{% notice warning %}}
Overclocking can cause issues in some games. The safest way to overclock is to increase the `Additional scanlines before NMI` option and leave the other options to their default values.
{{% /notice %}}
<div class="imgBox"><div>
<img src="/images/EmulationSettings_Overclocking.png" />
<span>Overclocking Options</span>
</div></div>
**Clock Rate Multiplier**: Use this to overclock or underclock the CPU -- this has the same effect as physically changing the clock speed on an actual NES. Unless you enable the `Do not overclock APU` option below, the audio output will be affected by this. ***This is not the recommended way to overclock the CPU.***
**Additional scanlines before NMI**: Increases the number of scanlines in the PPU, *before* the NMI signal is triggered at the end of the visible frame. This effectively gives more time for games to perform calculations, which can reduce slowdowns in games. **This is the preferred option for overclocking.**
**Additional scanlines after NMI**: Increases the number of scanlines in the PPU, *after* the NMI signal is triggered at the end of the visible frame. This effectively gives more time for games to perform calculations, which can reduce slowdowns in games. **This option is less compatible and should only be used if the `before NMI` variation does not work as expected.**
**Do not overclock APU**: When the `Clock Rate Multiplier` is not set to 100, the audio will be affected. When this option is enabled, the audio processor is not overclocked, which allows normal sound to be played despite the CPU being overclocked.
**Show Lag Counter**: When enabled, the lag counter is displayed on the screen. The lag counter keeps track of frames where the game does not attempt to read the input ports -- this is usually an indication of the game running out of time to perform calculations, which usually causes slowdowns.

59
Docs/content/configuration/Input.md Normal file
View file

@ -0,0 +1,59 @@
---
title: Input Options
weight: 5
chapter: false
---
## General Options ##
<div class="imgBox"><div>
<img src="/images/InputOptions_General.png" />
<span>Controller Options</span>
</div></div>
**Console Type**: Selects which console to emulate for all input ports. The `NES` and `Famicom` have different accessories and some of the identical accessories (e.g the Zapper) have different behavior on a hardware level. If you want to connect Famicom-only accessories that plug into the Famicom's expansion port, select `Famicom`.
**Automatically configure controllers when loading a game**: When enabled, when loading any game recognized by Mesen's internal game database, the appropriate controllers will automatically be setup. For example, loading up a game like Duck Hunt will connect a Zapper to the second port.
## Setting up controllers ##
### NES ###
For each player, select the device you want to use. To connect more than 2 controllers, check the `Use Four Score accessory` option.
To setup the key mappings for a controller (or other device-specific options), click the `Setup` button on the right of the player you want to configure.
### Famicom ###
On older Famicoms, the player 1 & 2 controllers are hard-wired and cannot be disconnected -- Mesen does the same. To connect additional controllers, select the `Four Player Adapter` expansion device.
To setup the key mappings for a controller (or other device-specific options), click the `Setup` button on the right of the player you want to configure.
## Configuring Key Bindings ##
<div class="imgBox"><div>
<img src="/images/InputOptions_Controller.png" />
<span>Controller Setup</span>
</div></div>
Each player can have up to four tabs of key bindings -- this allows you to control the same player with different input devices. For example, you can setup player 1 to be controlled by your keyboard and your Xbox controller at the same time.
To select a binding for a button, click on the corresponding button in the UI and then press the key or gamepad button you want to use for this button.
To clear a binding, click on it and then close the popup window by clicking on the X button.
To clear all bindings for this tab, click on the `Clear Key Bindings`.
To simplify configuration, a number of presets are available -- click on the `Select Preset` button to choose one.
You can also configure that controller's turbo buttons' speed with the `Turbo Speed` slider. *Note: setting the turbo speed to the fastest setting may cause some games to not detect the button presses at all.*
## Advanced Options ##
<div class="imgBox"><div>
<img src="/images/InputOptions_Advanced.png" />
<span>Advanced Options</span>
</div></div>
### Display Controller Input ###
Use these options to display the controller input on the screen.
{{% notice warning %}}
This will be recorded by the [Video Recorder](/tools.html#video-recorder) - so make sure you turn it off if you do not want it to appear on the video.
{{% /notice %}}

163
Docs/content/configuration/Preferences.md Normal file
View file

@ -0,0 +1,163 @@
---
title: Preferences
weight: 10
chapter: false
---
## General Options ##
<div class="imgBox"><div>
<img src="/images/Preferences_General.png" />
<span>General Options</span>
</div></div>
**Display Language**: Selects in which language the UI is shown -- defaults the user's default language.
**Automatically check for updates**: When enabled, Mesen will check for a new version of the emulator every time the emulator is started.
**Only allow one instance of Mesen at a time**: When enabled, only a single copy of Mesen can be opened at the same time. This is useful when using file associations to load games by double-clicking on the rom files.
### Pause/Background settings ###
**Hide the pause screen**: When enabled, the `PAUSE` screen is no longer shown when the emulator is paused.
**Pause when a movie finishes playing**: When enabled, the emulator will automatically pause when a movie ends its playback.
**Pause emulation when in background**: When enabled, the emulator will automatically pause when in the background.
**Allow input when in background**: When enabled, gamepad input can still be used even if the window is in the background. *This does not work for keyboard key bindings.*
### Misc. Settings ###
**Automatically apply IPS/BPS patches**: When enabled, any IPS or BPS patch file found in the same folder as the ROM file will automatically be applied. (i.e: when loading `MyRom.nes`, if a file called `MyRom.ips` exists in the same folder, it will be loaded automatically.)
**Automatically hide the menu bar**: When enabled, the menu bar will automatically be hidden when not in use, even in windowed mode. *The menu bar is always hidden automatically when playing in fullscreen mode, whether this option is enabled or not.*
**Display confirmation dialog before reset/power cycle/exit**: When enabled, a confirmation dialog will be shown before a reset or a power cycle or before the emulator is closed.
**Display play/record icon when playing or recording a movie**: When enabled, an icon will be shown on the screen whenever a movie is playing or recording.
**Enable developer mode**: When enabled, all debugging tools are moved to a `Debug` menu accessible directly from the main window. This makes debugging tools more accessible as they no longer require opening the debugger before being able to open any other tool.
## Shortcut Keys ##
<div class="imgBox"><div>
<img src="/images/Preferences_ShortcutKeys.png" />
<span>Shortcut Keys</span>
</div></div>
Shortcut keys are user-defined shortcuts for various features in Mesen. Some of these features can only be accessed via shortcut keys (e.g: `Fast Forward` and `Rewind`).
Most of these options are also available through the main window's menu -- the shortcuts configured in this section will appear next to the matching action in the main window's menu.
**To change a shortcut**, click on the button for the shortcut you want to change and press the key(s) you want to set for this shortcut. Once you release a key, all the keys you had pressed will be assigned to the shortcut.
**To clear a key binding**, right-click on the button.
Available shortcuts:
* **Fast Forward (Hold button)**: Hold down this key to fast forward the game.
* **Toggle Fast Forward**: Start/stop fast forwarding.
* **Rewind (Hold button)**: Hold down this key to rewind the game in real-time.
* **Toggle Rewind**: Start/stop rewinding.
* **Rewind 10 seconds**: Instantly rewinds 10 seconds of gameplay.
* **Rewind 1 minute**: Instantly rewinds 1 minute of gameplay.
* **Pause**: Pauses or unpauses the game.
* **Reset**: Resets the game.
* **Power Cycle**: Power cycles the game.
* **Power Off**: Powers off the game, returning to the game selection screen.
* **Exit**: Exits the emulator.
* **FDS - Insert Next Disk**: Inserts face A of the next disk.
* **FDS - Switch Side**: Switches to the current disk's other side (A or B)
* **FDS - Eject Disk**: Ejects the currently inserted disk
* **VS - Insert Coin 1**: Inserts a coin in slot 1.
* **VS - Insert Coin 2**: Inserts a coin in slot 2.
* **VS - Service Button**: Press to go to the service menu (only in some VS games)
* **Input Barcode**: Inputs a barcode into the connected barcode reader device.
* **Take Screenshot**: Takes a screenshot.
* **Load Random Game**: Loads a random game from your game folder.
* **Run Single Frame**: Press to run a single frame and pause.
* **Set Scale 1x to 6x**: Sets the scale to the matching value.
* **Toggle Fullscreen Mode**: Enters/exits fullscreen mode.
* **Toggle FPS Counter**: Turns on/off the FPS counter.
* **Toggle Game Timer**: Turns on/off the game timer.
* **Toggle Frame Counter**: Turns on/off the frame counter.
* **Toggle Lag Counter**: Turns on/off the lag counter.
* **Toggle OSD (On-Screen Display)**: Turns on/off the OSD.
* **Toggle Display on Top**: Turns on/off the display on top option.
* **Toggle Background Layer**: Turns on/off the background layer.
* **Toggle Sprite Layer**: Turns on/off the sprite layer.
* **Enable/Disable Cheat Codes**: Press to toggle cheats on or off.
* **Enable/Disable Audio**: Press to toggle audio output on or off.
* **Toggle Keyboard Mode**: Turns on/off keyboard mode.
* **Toggle Maximum Speed**: Toggles emulation speed between 100% and maximum speed.
* **Increase Speed**: Increases the emulation speed.
* **Decrease Speed**: Decreases the emulation speed.
* **Open File**: Displays the open file dialog.
* **Open Debugger**: Opens the debugger.
* **Open Assembler**: Opens the assembler.
* **Open Ppu Viewer**: Opens the PPU viewer.
* **Open Memory Tools**: Opens the memory tools.
* **Open Script Window**: Opens the script window.
* **Open Trace Logger**: Opens the trace logger.
* **Select Next Save Slot**: Move to the next save state slot.
* **Select Previous Save Slot**: Move to the previous save state slot.
* **Save State**: Save the game's state in the currently selected slot.
* **Load State**: Load the game's state from the currently selected slot.
* **Save State - Slot X**: Save the game's state to the matching slot.
* **Load State - Slot X**: Load the game's state from the matching slot.
* **Save State to File**: Save the game's state to a user-specified file.
* **Load State from File**: Load the game's state from a user-specified file.
## Folders and File Associations ##
<div class="imgBox"><div>
<img src="/images/Preferences_FoldersFiles.png" />
<span>Folders and File Associations</span>
</div></div>
**File Associations**: Use these options to associate Mesen with these file types. This will allow you to double-click on these files in a file explorer to open them in Mesen.
**Data Storage Location**: Mesen can either store its data in your user profile or in the same folder as the executable file itself. This is configured when you launch Mesen for the first time, but can also be changed here. When changing from one option to the other, Mesen will automatically copy all files from one folder to the other, allowing you to keep your save data and all other important files automatically.
**Folder Overrides**: On top of configuring the main folder where Mesen keeps its data, you may also specify custom locations for certain folders used by Mesen to store user-created files such as recordings or save data.
## Advanced Options ##
<div class="imgBox"><div>
<img src="/images/Preferences_Advanced.png" />
<span>Advanced Options</span>
</div></div>
**Disable built-in game database**: Mesen contains a built-in database containing information on thousands of rom files -- it uses this database to use the most appropriate settings when loading a game (e.g `NTSC` vs `PAL`) and to fix incorrect file headers. *Disabling this option is not recommended.*
**Keep rewind data for the last [x] minutes**: The rewind feature in Mesen periodically takes save states and keeps them in memory to allow the emulator to rewind the game. These save states take a minimal amount of memory (roughly 1MB per minute). To limit the amount of memory that Mesen can use for rewind data, this configures the number of minutes that it is possible to rewind for.
### FDS Settings ###
The FDS (Famicom Disk System) is a Famicom-specific add-on that allows games to be stored on special floppy disks. These options help simplify playing FDS games by allowing the emulation to fast-forward through load screens and automatically switch disk when needed.
**Automatically insert disk 1 side A when starting FDS games**: By default, the FDS boots with no disk inserted in the drive. This option makes it so the player does not need to manually insert disk 1, side A manually.
**Automatically fast forward FDS games when disk or BIOS is loading**: FDS games contain a large number of load screens due to their data being stored on floppy drives. Mesen needs to emulate this floppy drive's speed to ensure accurate emulation. This option makes it so Mesen runs the emulation as fast as it can when a game is loading data from the disk, which greatly reduces the time spent on loading screens.
**Automatically switch disks for FDS games**: FDS games are often split into multiple floppy disks, and each disk has 2 separate sides. Due to this, FDS games often ask the player to change disk, or flip to the other side. When this option is enabled, Mesen will attempt to detect when a game is asking for another disk and automatically insert it.
### UI Settings ###
**Always display on top of other windows**: When enabled, Mesen's window will always be displayed above all other windows.
**Disable on-screen display (OSD)**: When enabled, all on-screen messages are disabled.
**Display additional information in title bar**: When enabled, additional information is shown in the title bar (such as filter, scale, etc.), next to the game's name.
**Show frame counter**: When enabled, the number of frames emulated since the last reset will be shown on the screen.
**Show game timer**: When enabled, the amount of time elapsed since the last reset will be shown on the screen.
**Show game configuration dialog when loading VS System games**: VS System arcade cabinets usually have a number of options that can be physically configured via DIP switches in the arcade cabinet itself. When enabled, this option makes it so the DIP switches' configuration dialog is shown every time a VS System game is loaded. *This dialog can also be manually accessed from the `Game` menu.*
### Game Selection Screen Settings ###
**Start game from power-on instead of resuming the previous state**: Normally, when using the game selection screen to start a game, the game resumes where you left off. When this option is enabled, the game starts over from power on.
**Disable game selection screen**: When enabled, the game selection screen is hidden and cannot be used.

107
Docs/content/configuration/Video.md Normal file
View file

@ -0,0 +1,107 @@
---
title: Video Options
weight: 6
chapter: false
---
## General Options ##
<div class="imgBox"><div>
<img src="/images/VideoOptions_General.png" />
<span>General Options</span>
</div></div>
**Scale**: The scale determines the emulator window's size - use integer factors (e.g: 2x, 3x, 4x) for best results.
**Aspect Ratio**: The NES' internal aspect ratio is almost square (`Default (No Stretching)`), but it used to be displayed on CRT TVs that had a rectangular picture. To simulate a CRT TV, you can use the `Auto` option - it will switch between NTSC and PAL aspect ratios depending on the game you are playing. Using anything other than the `Default (No Stretching)` option may cause pixels to have irregular sizes. You can reduce this effect by using a combination of video filters and the bilinear filtering option.
**Enable integer FPS mode**: Under normal conditions, the NTSC NES runs at 60.1 fps. When playing a 60hz LCD, this causes a lot of dropped frames. This option slows down the emulation by a tiny amount to produce 60 frames per second instead, which reduces the number of dropped frames.
**Enable vertical sync**: Turns on vertical sync -- can help prevent screen tearing on some hardware configurations.
**Use exclusive fullscreen mode**: Turns on exclusive fullscreen mode. This may be useful if you are experiencing screen tearing issues in regular fullscreen despite vertical sync being turned on.
**Requested Refresh Rate**: This option is shown only when exclusive fullsceen mode is enabled. It allows you to select your preferred refresh rate when running in exclusive fullscreen mode.
**Use integer scale values when entering fullscreen mode**: By default, fullscreen mode fills the entire screen. However, this can cause non-integer scaling values to be used -- for example, in 1080p resolution, the scale becomes 4.5x. Since this can cause irregularly shaped pixels, you can use this option to use the nearest integer scale value instead (e.g 4x in this example).
**Use HDNes HD packs**: Enables the use of [HD packs](/hdpacks.html).
**Show FPS**: Displays an FPS counter on the screen. The first number is the number of frames emulated, the second number is the number of frames displayed on the screen. These values are usually identical, except when vertical sync is enabled.
**Overscan**: The overscan settings allow you to cut out pixels on any edge of the screen. On a CRT TV, a few pixels on each side of the screen was usually invisible to the player. Because of this, games often have glitches or incorrect palette colors on the edges of the screen -- this is normal and caused by the game itself. Setting a value of 8 or so on each side of the overscan configuration will usually hide most glitches.
## Picture ##
<div class="imgBox"><div>
<img src="/images/VideoOptions_Picture.png" />
<span>Picture Options</span>
</div></div>
**Filter**: Allows you to select a video filter. Selecting NTSC filters will cause additional configuration options to appear below.
### Common Options ###
The `Brightness`, `Contrast`, `Hue`, `Saturation`, `Scanline` settings are common to all filters and can even be used without a filter.
**Use bilinear interpolation when scaling**: When enabled, bilinear interpolation is used when stretching (due to scale or aspect ratio). When disabled, nearest neighbor scaling is used. An easy way to get a slightly-softened screen, for example, is to use the `Prescale` filters (which use nearest neighbor scaling), use a bigger scale and enable bilinear filtering. For example, try this configuration:
```text
Filter: Prescale 3x
Scale: 4x
Use bilinear interpolation when scaling: Enabled
```
**Scanlines**: Simulates the scanlines on a CRT TV - the higher the value, the deeper the scanlines appear on the screen.
### NTSC Filter Options ###
There are 2 separate NTSC filters implemented in Mesen. The `NTSC` filter is blargg's implementation - this filter is very fast, and available in various other emulators. The `NTSC (bisqwit)` filter is an implementation of bisqwit's NTSC filter -- it is slower and produces a different output.
The 2 filters have a different set of options:
**NTSC (blargg)**: `Artifacts`, `Bleed`, `Fringing`, `Gamma`, `Resolution`, `Sharpness`
**NTSC (bisqwit)**: `Y Filter (Horizontal Blur)`, `I Filter (Horizontal Blur)`, `Q Filter (Horizontal Bleed)`
Feel free to experiment with the settings and choose what you feel looks best.
## Palette ##
<div class="imgBox"><div>
<img src="/images/VideoOptions_Palette.png" />
<span>Palette Options</span>
</div></div>
This tab allows you to customize the palette used by all games.
{{% notice tip %}}
Click on any color in the palette to manually change its color.
{{% /notice %}}
**Load Preset Palette**: Mesen comes with a number of built-in palette options - you can select them from here.
**Load Palette File**: Use this to load a .pal file into the emulator.
**Export Palette**: Use this to export your current palette into a .pal file.
**Use this palette for VS System games**: By default, VS System games have their own predefined RGB palettes and don't use the palette defined here. When enabled, this option forces VS System games to ignore their default palette and use this one instead.
## Advanced Options ##
<div class="imgBox"><div>
<img src="/images/VideoOptions_Advanced.png" />
<span>Advanced Options</span>
</div></div>
{{% notice warning %}}
These options should not be used if you are looking for accurate emulation.
{{% /notice %}}
**Screen Rotation**: Rotates the display by the specified angle. This is useful to play games (generally homebrew games) designed for a vertical display.
**Disable background**: Disables rendering of the background layer.
**Disable sprite**: Disables rendering of all sprites.
**Force background display in first column**: The NES has a flag that prevents the background from rendering in the first 8 pixels on the left of the screen. When enabled, this option forces the background to be rendered in the first 8 pixels, no matter what the flag's value is.
**Force sprite display in first column**: The NES has a flag that prevents sprites from rendering in the first 8 pixels on the left of the screen. When enabled, this option forces the sprites to be rendered in the first 8 pixels, no matter what the flag's value is.

32
Docs/content/configuration/_index.md Normal file
View file

@ -0,0 +1,32 @@
---
title: Configuration
weight: 2
chapter: false
---
## Options Menu ##
<div class="imgBox right"><div>
<img src="/images/OptionsMenu.png" />
<span>Options Menu</span>
</div></div>
The options menu contains a number of shortcuts to change some popular settings:
**Speed**: Selects the emulation's current speed. Also see the [Rewind and Fast Forward shortcut keys](/configuration/preferences.html#shortcut-keys).
**Video Size**: Selects the picture's size -- when fullscreen is selected, the picture will automatically fill the screen. Additionally, you can also manually resize the window to select any size you prefer.
**Video Filter**: Selects a filter to apply to the picture. The `NTSC` filters attempt to reproduce the feeling of old CRT screens, while the other filters are a variety of different techniques used to scale up pixel art. Additional NTSC filter specific settings are available in the [video options](/configuration/video.html#picture).
**Region**: When set to `Auto`, the emulator will try to detect the game's region (NTSC or PAL) - however, this is not always possible. When there is nothing to suggest a game is for the `PAL` region (Australia & Europe), the `NTSC` region (North America & Japan) will be used by default. `Dendy` is used to mimic a number of different NES clones, in particular, the Dendy, which was a popular clone in Russia.
## Configuration Dialogs ##
Additional settings can be found in each of the available menu options:
* [Audio Options](/configuration/audio.html)
* [Input Options](/configuration/input.html)
* [Video Options](/configuration/video.html)
* [Emulation Options](/configuration/emulation.html)
* [Preferences](/configuration/preferences.html)

47
Docs/content/debugging/Assembler.md Normal file
View file

@ -0,0 +1,47 @@
---
title: Assembler
weight: 16
chapter: false
---
<div class="imgBox"><div>
<img src="/images/Assembler.png" />
<span>Assembler</span>
</div></div>
The assembler allows writing new code, editing existing code and running arbitrary code.
### Usage ###
Code is assembled on-the-fly, with the resulting byte code being shown on the right.
Any compilation error will be shown in the list at the bottom -- **<kbd>double-click</kbd>** an error in the list to navigate to the line that caused it.
Once you are done editing the code, you can either `Execute` it, or `Apply` it. Executing the code will make it run in the $3000-$3FFF memory range (temporarely overriding the PPU's normal behavior) and break the execution once the code is done executing. On the other hand, clicking `Apply` will write the code to the specified memory address - this can be used to create new code in RAM, for example, or alter existing code in PRG ROM.
{{% notice tip %}}
Any changes done to PRG ROM will remain in effect until a power cycle. If you want to save your modifications to a .nes file, or as an IPS patch, you can use the **<kbd>File&rarr;Save</kbd>** or **<kbd>File&rarr;Save edits as IPS</kbd>** commands in the [debugger window](/debugging/debugger.html).
{{% /notice %}}
**Note**: When [editing an existing block of code](/debugging/debugger.html#how-to-edit-code), the assembler keeps track of how many bytes of code the original code contained, as well as whether or not an RTS instruction was present. If the new code is lacking an RTS instruction, or is too large to fit into the original block of code, a warning will be shown before applying the changes.
### Supported features ###
* All official opcodes and addressing modes are fully supported.
* All unofficial opcodes with well-defined behavior are supported (see [limitations](#limitations) below)
* Hexadecimal ($ prefix) and decimal values are supported.
* Labels can be used and defined in the code. When using labels, the assembler will favor zero-page addressing when possible - only using other types of addressing when necessary.
* The `.byte` directive can be used to add arbitrary data to the output.
### Limitations ###
* **Unofficial opcodes**: The assembler supports all unofficial opcodes that Mesen can emulate. However, opcodes that have undefined behavior (and thus are not emulated by Mesen) are not supported. Additionally, name conflicts make it so it is impossible to use any NOP opcode other than the standard NOP opcode.
* **Defining labels**: As mentioned above, it is possible to define labels to use in the assembler. However, these labels are (currently) not permanent - they are discarded once the assembler is closed.
### Display Options ###
Syntax highlighting can be configured (or disabled) via the `View` menu.
It is also possible to change the font size.

287
Docs/content/debugging/Debugger.md Normal file
View file

@ -0,0 +1,287 @@
---
title: Debugger
weight: 10
pre: ""
chapter: false
---
<div class="imgBox"><div>
<img style="zoom:0.75" src="/images/DebuggerWindow.png" />
<span>The debugger window</span>
</div></div>
The debugger is the main part of the debugging tools available in Mesen. This window displays the disassembled code, allows you to configure breakpoints, labels and watch values. It also contains a large number of options and smaller features -- all of which are described below.
## General Usage Tips ##
Generally speaking, the debugger tries to mimic the look and feel of Visual Studio in a lot of ways, including a lot of keyboard shortcuts (especially if you use the C# shortcut settings in Visual Studio). If you are familiar with any version of VS, the debugger should be easy to use.
Most elements in the debugger's interface have right-click menu options - make sure you explore the right-click options available in each list and window.
Watch expressions, breakpoints and labels are automatically saved on a per-rom basis in a **Workspace**.
You can completely reset the workspace for a specific rom by using the **<kbd>File&rarr;Workspace&rarr;Reset Workspace</kbd>** command.
### Shortcuts ###
Use keyboard and mouse shortcuts to speed things up:
#### General ####
- <kbd>**F9**</kbd> to add/remove a breakpoint to the current line of code.
- <kbd>**Left-clicking**</kbd> on the left-most portion of the margin in the code window will set a breakpoint for that line.
#### Search and navigation ####
* <kbd>**Ctrl+F**</kbd>: To perform an incremental search in the code window.
* <kbd>**Ctrl-Shift-F**</kbd>: Find all occurrences of an address or label in the code window.
* <kbd>**Ctrl-G**</kbd>: Go to a specific address.
* <kbd>**Double-click**</kbd> on an address to navigate to it.
* <kbd>**Back/Forward**</kbd> mouse buttons (on a 5-button mouse) allow you to go back and forth in the navigation history.
## Code Window ##
<div class="imgBox"><div>
<img src="/images/CodeWindow.png" />
<span>Code Window</span>
</div></div>
The code window displays the disassembled code and contains a number of features and options.
### General information ###
* Several options control what is shown in the code window, and how it is shown - see [Display Options](#display-options) below.
* Labels and comments defined in the label list are shown in the code.
* Single-line comments appear on the left, multi-line comments appear on top.
* The instruction that's currently executing is highlighted in yellow.
* Mouse-hovering any label or address will display a tooltip giving additional information (label, comment, current value in memory, etc.)
* You can alter the flow of execution by using the `Set Next Statement` command to change the next instruction to be executed.
### Display Options ###
**Disassemble...**:
* **Verified code only**: The strictest disassembly mode - this will cause the dissassembler to only disassemble bytes that it knows to be actual code. Everything else will be treated as data.
* **Everything**: In this mode, the disassembler will attempt to disassemble absolutely everything, including bytes that are marked as data.
* **Everything except verified data**: In this mode, the disassembler will disassemble everything *except* bytes that have been used/marked as data.
**Display OP codes in lower case**: When enabled, OP codes are displayed in lowercase letters
**Highlight Unexecuted Code**: When enabled, code that has been identified by the disassembler as code but hasn't been executed yet will be highlighted in green.
**Show Effective Addresses**: When enabled, the resulting address of indirect addressing modes (e.g `LDA $3321, Y`) will be displayed next to the instruction in blue. e.g: `@ $3323`
**Show Only Disassembled Code**: When enabled, everything that has not been disassembled (e.g because it has not been confirmed to be actual code, or because it is data) will be hidden from the code window.
**Byte Code Display**: When enabled, the byte code matching the instructions will be displayed next to them (either on the left, or on the line below based on your selection)
**PRG Address Display**: When enabled, the address matching the actual position of an instructions in PRG ROM will be displayed next to the CPU address (or replace it entirely, based on your selection)
## Emulation Status ##
<div class="imgBox"><div>
<img src="/images/EmulationStatus.png" />
<span>Emulation Status</span>
</div></div>
This section of the debugger window displays the CPU and PPU's current state.
While execution is paused, most fields are editable. Altering the value of any field will change its corresponding value in the emulation core. To undo any edits you have done by mistake, click the "Undo Changes" button.
## Input Button Setup ##
<div class="imgBox"><div>
<img src="/images/InputButtonSetup.png" />
<span>Input Button Setup - P1's top and right buttons are pushed</span>
</div></div>
This section lets you force certain buttons to be held down on the NES' controller. This is often useful when trying to debug input-related code.
Clicking on a button on the mini NES controllers will toggle its state - green buttons are currently being held down.
## Watch Window ##
<div class="imgBox"><div>
<img src="/images/WatchList.png" />
<span>Watch Window</span>
</div></div>
The watch window allows you to evaluate expression and see their value. Mesen supports complex expressions in C/C++ style syntax.
**To add a new watch expression**, click on the last empty line in the list and start typing.
**To edit a watch expression**, double-click on it and start typing.
**To switch between hex and decimal**, right-click in the watch and toggle the **Hexadecimal Display** option.
### Syntax ###
The used syntax is identical to C/C++ syntax (e.g && for and, || for or, etc.) and should have the same operator precedence as C/C++.
**Note:** Use the $ prefix to denote hexadecimal values.
**Special values**
```text
A/X/Y/PS/SP: Value of corresponding registers
PC: Program Counter
OpPC: Address of the current instruction's first byte
Irq/Nmi: True if the Irq/Nmi flags are set
Cycle/Scanline: Current cycle (0-340)/scanline(-1 to 260) of the PPU
Frame: PPU frame number (since power on/reset)
Value: Current value being read/written from/to memory
IsRead: True if the CPU is reading from a memory address
IsWrite: True if the CPU is writing to a memory address
Address: Current CPU memory address being read/written
RomAddress: Current ROM address being read/written
[<address>]: (Byte) Memory value at <address> (CPU)
{<address>}: (Word) Memory value at <address> (CPU)
```
**Examples**
```
[$10] //Displays the value of memory at address $10 (CPU)
a == 10 || x == $23
scanline == 10 && (cycle >= 55 && cycle <= 100)
x == [$150] || y == [10]
[[$15] + y] //Reads the value at address $15, adds Y to it and reads the value at the resulting address.
{$FFFA} //Returns the NMI handler's address.
```
**Using labels**
Any label defined in the debugger can be used in watch expressions (their value will match the label's address in CPU memory).
For example, if you have a label called "velocity" that points to 1-byte value at address $30 in the CPU's memory, you can display its value in the watch using the following syntax: `[velocity]`
## Breakpoints ##
<div class="imgBox"><div>
<img src="/images/BreakpointList.png" />
<span>Breakpoint List</span>
</div></div>
Breakpoints define conditions under which the execution of the game's code will be suspended. Any number of breakpoints can be defined. To quickly add or remove a breakpoint for the current line of code, press F9 in the code window.
**To add a breakpoint**, right-click the breakpoint list and select **Add**.
**To edit a breakpoint**, double-click on it in the list.
**To disable a breakpoint**, uncheck it.
**To delete a breakpoint**, right-click on it and select **Delete**
**To view the breakpoint in the code**, right-click on it and select **Go to location**
### Breakpoint configuration ###
<div class="imgBox"><div>
<img src="/images/EditBreakpoint.png" />
<span>Edit Breakpoint Window</span>
</div></div>
Breakpoints can be set to trigger based on CPU/PPU memory accesses at specific memory addresses.
**Break On**
Select whether this breakpoint should occur based on CPU or PPU accesses, and which types of accesses should trigger the breakpoint.
**Address**
Select which address or address range this breakpoint should apply to.
It is also possible to specify no address at all by selecting **Any** - in this case, breakpoints will be evaluated on every CPU cycle.
**Use PRG ROM addresses**: This option makes it so the addresses apply to the PRG ROM itself, instead of their mappings in CPU memory.
**Condition** (optional)
Conditions allow you to use the same expression syntax as the one used in the [Watch Window](#watch-window) to cause a breakpoint to trigger under very specific conditions.
**Examples**
To break when the sum of the X and Y registers is 5:
x + y == 5
To break when the value at memory address $10 is smaller or equal to $40:
[$10] <= $40
To break when the CPU writes the value $60 to any address:
IsWrite && Value == $60
## Call Stack ##
<div class="imgBox"><div>
<img src="/images/CallStack.png" />
<span>Call Stack example with labels</span>
</div></div>
The call stack displays the currently executing function, and all functions that are below it on the stack.
The top of the list is the current function, while the row below it is the location that the code will return to once the current function executes the RTS instruction. The call stack also displays NMI and IRQ routine handlers and processes calls to RTI in the same manner as calls to JSR and RTS.
**Note:** Rows shown in gray and italic represent portions of the call stack that are currently not inside the CPU's memory (e.g because the PRG banks were changed since that point in the execution).
**Labels:** When labels are defined for the PRG ROM offset matching the function's entry point, that label is shown as the function's name in the call stack.
**To view the code** at any location in the call stack, double-click on the row.
## Labels ##
<div class="imgBox"><div>
<img src="/images/LabelList.png" />
<span>Label List</span>
</div></div>
Labels can be used to simplify debugging. They allow you to give names to variables and functions which will be used instead of numeric addresses when viewing the code in the debugger. Labels can also be used to display single and multi-line comments to the code.
The label list displays every label defined in alphabetical order.
**To add a label**, right-click in the label list and select `Add`.
**To edit a label**, right-click in the label list and select `Edit`.
**To delete a label**, right-click in the label list and select `Delete`.
**To find where a label is used**, right-click in the label list and select `Find Occurrences`.
**To view the code** at the label's location, double-click on the label in the list.
### Editing Labels ###
<div class="imgBox"><div>
<img src="/images/EditLabel.png" />
<span>Edit Label Window</span>
</div></div>
Various types of labels can be defined:
- **Internal RAM**: Used for labels residing in the $0000-$1FFF memory range (the NES' built-in RAM)
- **PRG ROM**: Used for constants, data, code labels and functions in PRG ROM - the address value represents the offset from the start of PRG ROM (which can exceed $FFFF)
- **Work RAM**: Used for variables in work ram (also called PRG RAM without battery backup) - the address value represents the offset from the start of the ram chip.
- **Save RAM**: Used for variables in work ram (also called battery-backed PRG RAM) - the address value represents the offset from the start of the ram chip.
- **Register**: These are used to give name to built-in or mapper-specific registers. For example, the $2000 PPU register could be renamed to "PpuControl".
There are some restrictions on what a label can contain -- in general, they must begin with a letter or an underscore and cannot contain spaces or most non-alphanumeric characters.
Every type of label can also contain a comment. Comments are shown in the code window as well as in the tooltips that are displayed when putting your cursor over a label in the code window.
## Function List ##
<div class="imgBox"><div>
<img src="/images/FunctionList.png" />
<span>Function List</span>
</div></div>
The function list is similar to the label list and allows you to easily add or edit the name of functions (which are also labels).
Unlike the label list, which only displays labels, the function list displays all known functions, including those with no labels. This is useful to quickly check an unnamed function's code (by double-clicking on it) and give it a name. This can help when attempting to reverse-engineer code.
## CPU/PPU Memory Mappings ##
<div class="imgBox inline"><div>
<img src="/images/CpuPpuMapping.png" />
<span>CPU/PPU Memory Mappings</span>
</div></div>
The CPU and PPU memory mappings are visual aids that display information about the currently selected PRG/CHR banks and the nametable configuration.
The banking configuration represents Mesen's internal representation of the mapper in use, which may not exactly match the mapper's specs.
For example, a mapper with 2x 8kb + 1x 16kb PRG banking is emulated as 4x 8kb internally, so it will appear as 4 8kb banks.
## How To: Edit Code ##
<div class="imgBox"><div>
<img src="/images/EditCodeExample.png" />
<span>Using "Edit Selected Code" from the code window allows you to edit the code in the assembler</span>
</div></div>
From the code window, you can select code (via click and drag, or shift+arrow keys) and use the "Edit Selected Code" command to open the [Assembler](/debugging/assembler.html) and edit that section of code.
The assembler recognizes labels and allows you to define temporary labels as well. If the new code is smaller (in terms of bytes) than the original code, the extra bytes will be replaced by NOPs. If the new code is larger, it will override whatever comes next in the code -- a warning will be shown beforehand in this case.
When you're ready to apply your modifications, press the Apply button.
{{% notice tip %}}
If you want to save your code modifications to a .nes file, or as an IPS patch, you can use the **<kbd>File&rarr;Save</kbd>** or **<kbd>File&rarr;Save edits as IPS</kbd>** commands.
{{% /notice %}}

29
Docs/content/debugging/DebuggerIntegration.md Normal file
View file

@ -0,0 +1,29 @@
---
title: Integration with CC65/ASM6
weight: 18
pre: ""
chapter: false
---
When building homebrew software in assembly or C, it is possible to export the labels used in your code and import them into Mesen to simplify the debugging process. This allows the debugger to know which portions of the ROM correspond to which functions in your code, as well as display your code's comments inside the debugger itself.
## CC65 / CA65 ##
CC65/CA65 are able to produce .DBG files which can be imported into Mesen's debugger.
To make CC65/CA65 create a .DBG file during the compilation, use the `--dbgfile` command line option.
To import the .DBG file, use the **<kbd>File&rarr;Workspace&rarr;Import Labels</kbd>** command in the debugger window.
You can also enable the `Auto-load DBG/MLB files` to make Mesen load any .DBG file it finds next to the ROM whenever the debugger is opened or the power cycle button is used.
**Note:** For this option to work, the ROM file must have the same name as the DBG file (e.g `MyRom.nes` and `MyRom.dbg`) and be inside the same folder.
## ASM6f ##
Integration with ASM6 is possible by using freem's branch of ASM6 named [ASM6f](https://github.com/freem/asm6f).
This fork contains 2 additional command line options that are useful when using Mesen: `-m` and `-c`
`-m` produces a .mlb (Mesen labels) file that can be imported manually using the **<kbd>File&rarr;Workspace&rarr;Import Labels</kbd>** command.
`-c` produces a .cdl (Code Data Logger) file which can be imported manually using the **<kbd>Tools&rarr;Code/Data Logger&rarr;Load CDL file</kbd>** command.
Additionally, you can use the `Auto-load DBG/MLB files` and `Auto-load CDL files` options in the **<kbd>File&rarr;Workspace</kbd>** menu to automatically load MLB and CDL files present in the same folder as the current ROM, with the same filename (e.g `MyRom.nes`, `MyRom.mlb`, `MyRom.cdl`).

104
Docs/content/debugging/MemoryTools.md Normal file
View file

@ -0,0 +1,104 @@
---
title: Memory Tools
weight: 14
chapter: false
---
## Memory Viewer ##
<div class="imgBox"><div>
<img src="/images/HexEditor.png" />
<span>Memory Viewer</span>
</div></div>
The memory viewer offers read and write access to all types of ROM and RAM:
* CPU Memory
* PPU Memory
* Palette RAM
* OAM RAM
* Secondary OAM RAM
* PRG ROM
* CHR ROM
* CHR RAM
* Work RAM
* Save RAM
{{% notice tip %}}
PRG ROM and CHR ROM *are* writable from the memory viewer. Any change will remain in effect until a power cycle. If you want to save your PRG/CHR ROM modifications to a .nes file, or as an IPS patch, you can use the **<kbd>File&rarr;Save</kbd>** or **<kbd>File&rarr;Save edits as IPS</kbd>** commands in the [debugger window](/debugging/debugger.html).
{{% /notice %}}
### Editing Memory Values ###
There are 2 ways to edit memory values:
* **Using the hex view**: Click on the byte you want to change in the hex view (on the left), and type hexadecimal values to replace it.
* **Using the text view**: Click on the section you want to change in the text view (on the right), and type ASCII text to replace. This method is rather limited and usually not very useful unless the ROM uses ASCII values for its text.
### Importing / Exporting ###
For most types of memory, it is possible to export its contents to a binary file as well as import it back from a file. Use the `Import` and `Export` commands to do this.
### Highlighting ###
There are a number of highlighting/coloring options in the memory viewer.
<kbd>**View&rarr;Highlight**</kbd> has coloring options for addresses that were recently read, written or executed (colored in <span class="blue">blue</span>, <span class="red">red</span> and <span class="green">green</span>, respectively). A fade-out period can also be configured, after which the byte will revert to its normal black color.
<kbd>**View&rarr;De-emphasize**</kbd> offers options to display bytes matching certain conditions (unused, read, written or executed) in <span class="gray">gray</span>.
### Freezing values ###
Using the right-click menu, you can `Freeze` values in CPU Memory. Frozen addresses are shown in <span class="magenta">magenta</span>.
Frozen addresses will no longer be affected by write operations - effectively making those addresses read-only for the CPU. It is still possible to manually edit the value of frozen addresses using the memory viewer.
### Using TBL Files ###
<div class="imgBox"><div>
<img src="/images/HexEditorTbl.png" />
<span>Memory Viewer with a TBL file loaded to display Japanese text</span>
</div></div>
TBL files are text files that define mappings between sequences of bytes and text characters. For example, it might define the byte $95 as the character 'A'.
Normally, when no TBL file is loaded, the memory viewer will display each byte's standard ASCII representation on the right-hand side.
Once a TBL file is loaded, the text representation of the data will be updated to reflect the TBL mappings. This is useful, for example, when translating text.
## Memory Access Counters ##
<div class="imgBox"><div>
<img src="/images/MemoryAccessCounters.png" />
<span>Memory Access Counters</span>
</div></div>
When active, the debugger keeps track of all CPU and PPU memory reads, writes and executions. It is possible to view these counters here.
Use the `Sort By` option to sort the list based on different criteria.
The `Reset` button allows you to reset all counters back to 0 -- this is useful when you are trying to gather data for a specific portion of the execution.
Use the `Highlight uninitialized memory reads` option to track down any reads done to RAM memory before the RAM memory has been initialized after a power cycle -- reading from uninitialized memory can produce random behavior, which is usually unwanted.
## Profiler ##
<div class="imgBox"><div>
<img src="/images/Profiler.png" />
<span>Code Profiler</span>
</div></div>
The profiler automatically collects data about all function calls done by the code, as well as the number of clock cycles spent in each respective function.
Using the profiler makes it is easy to find the bottlenecks in a game's code, which can help code optimization efforts.
If you are familiar with Visual Studio's profiler, these columns should be familiar:
* **Call Count**: The number of times this function was called during profiling
* **Inclusive Time (Cyc)**: The amount of CPU cycles spent within this function (including the cycles spent by all functions called by this function)
* **Inclusive Time (%)**: The relative portion of CPU time spent within this function (including the time spent by all functions called by this function)
* **Exclusive Time (Cyc)**: The amount of CPU cycles spent within this function (functions called by this function are excluded)
* **Exclusive Time (%)**: The relative portion of CPU time spent within this function (functions called by this function are excluded)
* **Call Count**: The number of times this function was called during profiling
Use the `Reset` button to reset the profiler's data -- use this when you want to profile a specific portion of the execution.

91
Docs/content/debugging/PpuViewer.md Normal file
View file

@ -0,0 +1,91 @@
---
title: PPU Viewer
weight: 10
pre: ""
chapter: false
---
The PPU Viewer is a collection of tools allowing you to view/edit the current state of various parts of the PPU's memory: nametable RAM, CHR ROM/RAM, palette RAM and OAM (sprite) RAM.
All tabs share some common settings:
* **Auto-refresh**: Enabled by default, this makes the PPU viewer refresh at a rate of 15 FPS.
* **When emulation is running, show PPU data at scanline [y] and cycle [x]**: When using the auto-refresh option, this allows you to control at which point in a frame (cycle & scanline) the data is refreshed while the emulation is running. This is useful for games that perform CHR bank switching in the middle of a frame, for example.
## Nametable Viewer ##
<div class="imgBox"><div>
<img src="/images/NametableViewer.png" />
<span>Nametable Viewer</span>
</div></div>
The nametable viewer displays the contents of all 4 nametables (PPU addresses $2000 to $2FFF).
Mouve-over a tile to display that tile's information on the right.
There are also a number of display options:
* **Show PPU Scroll Overlay**: Shows a blue rectangular overlay showing the current scroll position of the screen.
* **Show Tile Grid**: Displays a 8x8 pixels <span class="red">red</span> grid.
* **Show Attribute Grid**: Displays a 16x16 pixels <span class="blue">blue</span> grid.
* **Highlight tile selected in CHR viewer**: When enabled, click on a tile in the CHR viewer to select it, all occurrences of that tile will then be marked by a <span class="red">red</span> rectangle in the nametable viewer.
<kbd>**Double-click**</kbd> on a tile in the nametable viewer to view/edit it in the CHR Viewer.
Additionally, you can <kbd>**right-click**</kbd> on a tile to copy the tile's information to the clipboard (for use with [HD Packs](/hdpacks.html)).
## CHR Viewer/Editor ##
<div class="imgBox"><div>
<img src="/images/ChrViewer.png" />
<span>CHR Viewer and Editor</span>
</div></div>
The CHR Viewer tab displays up to 2 4kb banks of CHR data at once. It can display any portion of CHR RAM/ROM, even banks that are not currently selected.
It also doubles up as a very simple graphic editor.
You can <kbd>**right-click**</kbd> on a tile to copy the tile's information (based on the currently selected palette) to the clipboard (for use with [HD Packs](/hdpacks.html)).
### Display Options ###
* **Chr Selection**: Select which portion of CHR memory to display in the viewer - by default, the portions of CHR memory mapped to the $0000-$1FFF range in PPU memory are shown.
* **Palette Selection**: Selects which palette to use to render the tiles - the first 4 palettes are for tiles, the last 4 palettes are for sprites.
* **Highlight**: This option allows tiles to be highlighted/dimmed based on the CDL file's current data. This makes it possible to highlight/dim tiles that have never been drawn by the PPU, or vice versa. *This option is only available for CHR ROM games*.
* **Display as 16x8 sprites**: When enabled, changes the display order of the tiles to make it easier to visualize 16x8 sprites.
### Editing Tiles ###
To edit a tile, first click on the tile you want to edit in the left-side of the window. This will select the tile and highlight it with a transparent square.
You can select the color you want to use by clicking on the `Color Picker`. You can also press keys 1 to 4 on your keyboard to quickly switch between the four colors.
With a tile selected, move your mouse to the tile preview above the `Color Picker` and **<kbd>click+drag</kbd>** to start drawing. **<kbd>Right-click</kbd>** can be used to draw as well -- it always draws color #0.
{{% notice tip %}}
Any change will remain in effect until a power cycle. If you want to save your modifications to a .nes file, or as an IPS patch, you can use the **<kbd>File&rarr;Save</kbd>** or **<kbd>File&rarr;Save edits as IPS</kbd>** commands in the [debugger window](/debugging/debugger.html). Keep in mind that edits done to CHR RAM *cannot* be saved.
{{% /notice %}}
## Sprite Viewer ##
<div class="imgBox"><div>
<img src="/images/SpriteViewer.png" />
<span>Sprite Viewer</span>
</div></div>
The Sprite Viewer displays the contents of OAM RAM. Mouve-over a sprite to display that sprite's information on the right.
The `Screen Preview` displays all sprites as they will be shown on the screen, based on the current OAM data.
Like the nametable viewer, <kbd>**double-click**</kbd> on a tile to view/edit it in the CHR Viewer -- this works in the `Screen Preview` as well.
Additionally, you can <kbd>**right-click**</kbd> on a tile to copy the tile's information to the clipboard (for use with [HD Packs](/hdpacks.html)).
## Palette Viewer/Editor ##
<div class="imgBox"><div>
<img src="/images/PaletteViewer.png" />
<span>Palette Viewer and Editor</span>
</div></div>
The Palette Viewer displays basic information about the current state of palette RAM.
It shows which colors are configured in each of the 8 available palettes.
You can click on any color to select another color for that slot.

23
Docs/content/debugging/ScriptWindow.md Normal file
View file

@ -0,0 +1,23 @@
---
title: Script Window
weight: 17
chapter: false
---
<div class="imgBox"><div>
<img src="/images/ScriptWindow.png" />
<span>Script Window</span>
</div></div>
The Script Window allows [Lua](https://www.lua.org/) scripting via a [Mesen-specific API](/apireference.html). Using this API, you can interact with the emulation core to perform a variety of things (e.g: logging, drawing, implementing an AI).
The code editor contains an autocomplete feature for all of Mesen's API -- typing `emu.` will display an autocomplete popup displaying all available functions. Select a function in the list to see its parameters, return value and description.
Multiple script windows can be opened at once to combine the effects of several scripts together.
Scripts can be loaded from the disk and edited in any other text editor. When using an external editor to modify the script, it is suggested to turn on the **<kbd>Script&rarr;Auto-reload when file changes</kbd>** option to automatically reload the script each time it is saved to the disk.
To start a script, press **<kbd>F5</kbd>**.
To stop a script, press **<kbd>Escape</kbd>** or close the script window.
The Log Window at the bottom will display any Lua errors that occur while running the script.
Additionally, any calls to `emu.log()` will also display their content in the log window.

31
Docs/content/debugging/TraceLogger.md Normal file
View file

@ -0,0 +1,31 @@
---
title: Trace Logger
weight: 15
chapter: false
---
<div class="imgBox"><div>
<img src="/images/TraceLogger.png" />
<span>Trace Logger</span>
</div></div>
### Basic Information ###
The trace logger displays the execution log of the CPU. It can display the last 30,000 CPU instructions executed. Additionally, it is also possible to log these instructions to the disk by using the `Start Logging` button. Log files can rapidly grow in size (to several GBs worth of data in a few seconds), so it is recommended to log for the shortest amount of time needed.
### Display Options ###
A number of options that toggle the display of several elements exist: `Registers`, `CPU Cycles`, `PPU Cycles`, `PPU Scanline`, `Show Effective Addresses`, `Byte Code`, `Frame Count`, `Additional Information (IRQ, NMI, etc.)`. Adjust these based on your needs.
Additionally, you can alter the way some elements are displayed:
* **Status Flag Format**: Offers a number of different ways to display the CPU's status flags.
* **Indent code based on stack pointer**: When enabled, the log's lines will be indented by 1 character for every byte pushed to the stack. This is useful to quickly be able to identify function calls, for example.
* **Use Labels**: When enabled, addresses that match known labels will be replaced by their label instead.
### Conditional Logging ###
The `Condition` field accepts conditional statements in the same format as [breakpoints](/debugging/debugger.html#breakpoint-configuration).
When a condition is entered, only instructions that match the given condition will be logged. This can be used, for example, to log cartridge register writes (e.g: `IsWrite && Address >= $8000`), PPU register reads (e.g: `IsRead && Address >= $2000 && Address <= $3FFF`) or when a specific portion of CPU memory is being executed (e.g: `pc >= $8100 && pc <= $8150`).
Conditions are very flexible and can be used to check just about any condition -- use them to your advantage.

21
Docs/content/debugging/_index.md Normal file
View file

@ -0,0 +1,21 @@
---
title: Debugging Tools
weight: 5
chapter: false
toc: false
---
The debugging capabilities of Mesen are split across a number of different tools, including the debugger itself:
[Assembler](/debugging/assembler.html): Allows you to edit a game's code or run custom code on-the-fly.
[Debugger](/debugging/debugger.html): View the code, add breakpoints, labels, watch values, and much more.
[Memory Tools](/debugging/memorytools.html): Contains a hex editor and performance profiler.
[PPU Viewer](/debugging/ppuviewer.html): Displays information on the nametables, sprites, CHR banks and palette. Contains a CHR graphic editor and a palette editor.
[Script Window](/debugging/scriptwindow.html): Allows the execution of Lua scripts, which can communicate with the emulation via an API.
[Trace Logger](/debugging/tracelogger.html): View or log to a file the execution trace of the CPU and PPU.
Additionally, some other smaller features are available from the main debugger window. e.g:
- [Import labels from CA65/CC65 or ASM6](/debugging/debuggerintegration.html)
- Save any modification done to PRG/CHR ROM via the [CHR Viewer](/debugging/ppuviewer.html#chr-viewer), [Assembler](/debugging/assembler.html) or the [Memory Viewer](/debugging/memorytools.html#memory-viewer) as a new `.nes` file, or as an `.ips` patch file
- Edit a rom's iNES header

147
Docs/content/gettingstarted/_index.md Normal file
View file

@ -0,0 +1,147 @@
---
title: Getting Started
weight: 1
chapter: false
---
## System Requirements ##
### Windows ###
* Windows Vista, 7, 8, 8.1 and 10 are supported
* DirectX 11
* .NET Framework 4.5+
### Linux ###
* glibc 2.24+
* Mono 4.2.1+
* SDL 2
## Installation ##
<div class="imgBox right"><div>
<img src="/images/ConfigWizard.png" />
<span>Configuration Wizard</span>
</div></div>
There is no actual installer for Mesen -- run the Mesen.exe application and a first-run configuration wizard will be shown.
**Data Storage Location**: This section of the wizard allows you to select where you prefer to keep Mesen's files.
**Input Mappings**: Select which input types you want to use to play games. There are built-in presets for:
* Xbox controllers
* PS4 controllers
* WASD keyboard layout
* Arrow keyboard layout
You can select multiple presets at once, but only a single keyboard layout.
**Create a shortcut on my desktop**: Check this option if you want to add a Mesen shortcut to your desktop.
## Using Mesen ##
<div class="imgBox right"><div>
<img src="/images/GameMenu.png" />
<span>Game Menu</span>
</div></div>
Mesen's default configuration should work out of the box and allow you to get right into playing games.
To load a game, use the **<kbd>File&rarr;Open</kbd>** command and select any supported file (`.nes`, `.fds`, `.nsf`, `.nsfe`, `.unf`) you want to load.
Once a game is loaded, you can pause, reset or stop the game via the `Game` menu.
The game menu also contains additional options for [Famicom Disk System (FDS)](#famicom-disk-system-fds-games) games and [VS System](#vs-system-games) games.
### Famicom Disk System (FDS) games ###
<div class="imgBox right"><div>
<img src="/images/FdsGameMenu.png" />
<span>FDS Game Menu</span>
</div></div>
{{% notice warning %}}
FDS games require a BIOS file. When you load a FDS game for the first time, Mesen will ask you for the BIOS file -- without one, running FDS games is not possible.
{{% /notice %}}
FDS games were originally stored on floppy disks - sometimes split across multiple disks and disk sides. The `Game` menu contains a number of additional shortcuts for FDS games to handle these:
* **Switch Disk Side**: Switches between sides A and B of the current disk.
* **Select Disk**: Allows you to select any disk and side combination availble for the current game.
* **Eject Disk**: Ejects the current disk. *Ejecting the disk is usually unnecessary and only available for the sake of completeness.*
<div class="clear"></div>
### VS System games ###
<div class="imgBox right"><div>
<img src="/images/VsGameMenu.png" />
<span>VS System Game Menu</span>
</div></div>
VS System games were originally in the form of arcade cabinets -- unlike FDS games, playing them does not require any special BIOS.
Being arcade cabinets, VS System games typically require the player to insert coins before the game can be played. Additionally, the arcade cabinets could often be configured via a number of physical DIP switches -- for example, to select how much money needs to be inserted to play, or to alter a game's difficulty. The `Game` menu offers additional options when playing VS System games to handle these:
* **Game Configuration**: Displays a configuration dialog containing the DIP switch options available for this game.
* **Insert Coin 1**: Inserts a coin into the first coin slot.
* **Insert Coin 2**: Inserts a coin into the second coin slot.
<div class="clear"></div>
### NSF Player ###
<div class="imgBox"><div>
<img src="/images/NsfPlayer.png" />
<span>Mesen's NSF Player</span>
</div></div>
NSF and NSFe files are used to store music from NES and Famicom games.
When loading NSF files into Mesen, the UI will change into a media player style UI. From this UI, you can control the volume, select the track, pause the music or fast forward by holding down the mouse button.
Additionally, the two icons at the top right allow you to toggle the repeat and shuffle playback modes.
<div class="clear"></div>
### Game Selection Screen ###
<div class="imgBox"><div>
<img src="/images/GameSelectionScreen.png" />
<span>Game Selection Screen</span>
</div></div>
The game selection screen is shown when no games are currently loaded -- it will display the last 5 games you've played, along with a screenshot of the game at the point where you left off playing.
You can use this screen via the key bindings for player 1 - e.g press `Left` or `Right` on Player 1's d-pad to change game, and the `A` button to start the game. You can also navigate the screen with your mouse -- use the arrows on each side of the screen to change game, and click on the game's screenshot to start playing.
<div class="clear"></div>
### Shortcut Keys ###
Mesen has a number of shortcut keys that you may find useful:
* <kbd>**Ctrl-O**</kbd>: Open a file
* <kbd>**Ctrl-R**</kbd>: Reset the game
* <kbd>**Escape**</kbd>: Pause/resume the game
* <kbd>**F1 to F8**</kbd>: Load save state in the corresponding slot.
* <kbd>**Shift-F1 to Shift-F7**</kbd>: Save a save state in the corresponding slot.
* <kbd>**Ctrl-S**</kbd>: Manually save a save state to a file.
* <kbd>**Ctrl-L**</kbd>: Manually load a save state from a file.
* <kbd>**Alt-1 to Alt-6**</kbd>: Change the video scale.
Additionally, there are a large number of customizable [shortcut keys](/configuration/preferences#shortcut-keys) in the [preferences](/configuration/preferences.html).
<div class="clear"></div>
### Command-line Options ###
<div class="imgBox"><div>
<img src="/images/CommandLineOptions.png" />
<span>Command-line Options</span>
</div></div>
Mesen supports a large number of command-line options.
To see a full list and some examples, click on the **<kbd>Help&rarr;Command-line Options</kbd>** menu option.

186
Docs/content/hdpacks/_index.md Normal file
View file

@ -0,0 +1,186 @@
---
title: HD Packs
weight: 5
chapter: false
---
HD Packs make it possible to replace a game's graphics and audio with high definition alternatives. This can be used in many ways, for example, one could keep the game's original resolution and simply improve its graphics by adding more colors and shading.
## Using HD packs ##
To use HD packs, first make sure to turn on the [Enable HDNes HD Packs](/configuration/video.html#general-options) option.
To install a HD Pack, you should extract it in a subfolder inside the `HdPacks` folder in Mesen's data folder. You can open this folder by clicking on the `Open Mesen Folder` button in the [Preferences](/configuration/preferences.html#general-options) window.
The subfolder should have the same name as the rom file itself.
For HD packs created with Mesen's [HD Pack Builder](#using-the-hd-pack-builder), you can also put them in `.zip` format in the `HdPacks` folder, without unzipping them nor worrying about renaming the file.
## Using the HD Pack Builder ##
<div class="imgBox"><div>
<img src="/images/HdPackBuilder.png" />
<span>HD Pack Builder</span>
</div></div>
The HD Pack Builder can be used to record a game's graphics into PNG image files and build a matching `hires.txt` file. These are the 2 basic elements needed for HD Packs: a tile map (the PNG files) and a definition file that specifies where each tile is on the tile map (the `hires.txt` file).
The basic concept of this tool is to use it to record gameplay of a game from start to finish, attempting to trigger every possible animation or graphics during gameplay. This will create a complete set of tiles (saved in PNG files) and a single hires.txt file that contains all that is needed to replace the tiles with HD tiles. Once this is done, the only thing left to do, in most cases, is to replace the graphics in the PNG files with better alternatives (e.g higher resolution, more colors, etc.).
A number of options exist to control the way the PNG files are generated:
**Scale/Filter**: Selects the scale and video filter to use when generating the PNG files for the HD Pack. Use the "Prescale" filters to generate the tiles at a larger scale without applying any transformation to the pixels.
**CHR Bank Size**: This option is only available for CHR RAM games. CHR RAM games have no fixed "banks" - they are dynamically created by the game's code. This option alters the HD Pack Builder's behavior when grouping the tiles into the PNG files - a smaller bank size will usually result in less PNG files (but depending on the game's code, larger values may produce better results).
**Group blank tiles**: This option groups all the blank tiles sequentially into the same PNG files - this helps reduce the number of PNG files produced by removing almost-empty PNG files containing only blank tiles.
**Sort pages by usage frequency**: When this option is enabled, the tiles in PNG files are sorted by the frequency at which they are shown on the screen while recording (more common palettes will be grouped together in the first PNG for a specific bank number. If this option is unchecked, the PNGs will be sorted by palette - each PNG will only contain up to 4 different colors in this case.
**Use 8x16 sprite display mode**: When enabled, this option will alter the display order of CHR banks that contain only sprites to make the sprites easier to edit in the PNG file.
**Ignore tiles at the edges of the screen (overscan)**: When enabled, this will make the builder ignore any pixels in the overscan area. This is useful in games that contain glitches on the outer edge of the screen. Incorrect palette combinations due to these glitches will be ignored and won't be shown in the PNG files.
Before you start recording, select the options you want to use and the location to which you want to save the HD Pack, then press the `Start Recording` button.
## File Format (hires.txt) ##
The following are the specifications for the hires.txt file, as of version "100".
### &lt;ver&gt; tag ###
**Syntax**: `<ver>[integer]`
**Example**: `<ver>100`
The format's version number -- this is currently 100 for Mesen.
### &lt;scale&gt; tag ###
**Syntax**: `<scale>[integer]`
**Example**: `<scale>4`
The scale used for the replacement graphics -- this can be any integer number (minimum: 1). Anything above 8-10x will probably have a very hard time running on any computer. It is suggested to use scales between 1x and 4x.
### &lt;overscan&gt; tag ###
**Syntax**: `<overscan>[top],[right],[bottom],[left]`
**Example**: `<overscan>8,8,8,8`
The overscan values to use when the HD Pack is loaded - this is useful for games that produce glitches on the edges of the screen.
### &lt;patch&gt; tag ###
**Syntax**: `<patch>[filename],[sha1 hash]`
**Example**: `<patch>MyPatch.ips,26aec27ef0fc1a6fd282937b918ebdd1fb480891`
Specifies a patch file to apply if the loaded ROM matches the specified SHA1 hash.
The patches can be in either `.ips` or `.bps` format.
Multiple `<patch>` tags with different SHA1 hashes can be present in the same `hires.txt` file.
### &lt;img&gt; tag ###
**Syntax**: `<img>[filename]`
**Example**: `<img>Tileset01.png`
Specifies a PNG file that contains tile graphics -- each `<img>` tag is indexed (starting from 0) according to the order it appears in the `hires.txt` file, the tag's index must be used when using `<tile>` tags.
### &lt;condition&gt; tag ###
**Syntax**: `<condition>[name - text], [conditionType - text], [x value - integer], [y value - integer], [tile data], [palette data - hex]`
**Example (CHR ROM)**: `<condition>myCondition,tileNearby,8,0,10,0F100017`
**Example (CHR RAM)**: `<condition>myCondition,tileNearby,8,0,D2C2C2C7CF2FFEFC2C3C3C3830D00000,0F100017`
For CHR ROM games, `tile data` is an integer representing the position of the original tile in CHR ROM.
For CHR RAM games, `tile data` is a 32-character hexadecimal string representing all 16 bytes of the tile.
`palette data` is always an 8-character hexadecimal string representing all 4 bytes of the palette used for the tile. For sprites, the first byte is always "FF".
`conditionType` can be any of: `tileAtPosition`, `tileNearby`, `spriteAtPosition` and `spriteNearby`.
`tileAtPosition` and `spriteAtPosition` use the X/Y parameters as screen coordinates. e.g:
`<condition>myCondition,tileAtPosition,10,10,[tile data],[palette data]`
In this case, `myCondition` will be true if the tile at position 10,10 on the NES' screen (256x240 resolution) matches the tile+palette data given.
`tileNearby` and `spriteNearby` use positive or negative X/Y offsets to the current position. e.g:
`<condition>myCondition2,tileNearby,-8,0,[tile data],[palette data]`
In this case, `myCondition2` will be true if the tile 8 pixels to the left of the current tile matches the tile+palette data specified.
### &lt;tile&gt; tag ###
**Syntax**: `<tile>[img index - integer], [tile data], [palette data], [x - integer], [y - integer], [brightness - 0.0 to 1.0], [default tile - Y or N]`
**Example (CHR ROM)**: `<tile>0,20,FF16360F,0,0,1,N`
**Example (CHR RAM)**: `<tile>0,0E0E079C1E3EA7076101586121010000,0F100017,176,1168,1,N`
For CHR ROM games, `tile data` is an integer representing the position of the original tile in CHR ROM.
For CHR RAM games, `tile data` is a 32-character hexadecimal string representing all 16 bytes of the tile.
`palette data` is always an 8-character hexadecimal string representing all 4 bytes of the palette used for the tile. For sprites, the first byte is always "FF".
`<tile>` define mappings between the original game's tile data and their replacements in the PNG file.
The `tile data` and `palette data` are used to identify the original tile, while the `img index`, `x` and `y` fields are used to specify in which PNG file the replacement can be found, and at what x,y coordinates in that PNG file.
`brightness` can be used to reuse the same HD tile for multiple original tiles -- this can be useful when a game has fade in and out effects.
When `default tile` is enabled (with `Y`), the tile is marked as the `default tile` for all palettes. Whenever a tile appears on the screen that matches the tile data, but has no rules matching its palette data, the default tile will be used instead.
### &lt;background&gt; tag ###
**Syntax**: `<background>[name - text], [brightness level - 0.0 to 1.0]`
**Example**: `<background>myBackground.png,1.0`
`<background>` tags meant to be used alongside conditions to add a background image under certain conditions (e.g on a specific screen, for example).
### &lt;options&gt; tag ###
**Syntax**: `<options>[option1 - text], [...]`
**Example**: `<options>disableSpriteLimit`
Currently, the only flag available is `disableSpriteLimit` which forces the emulator to disable the sprite limit when the HD pack is loaded.
### &lt;bgm&gt; tag ###
**Syntax**: `<bgm>[album - integer],[track - integer],[filename - ogg]`
**Example**: `<bgm>0,0,myBgm.ogg`
Used to assign a background music track (`.ogg` audio file) to a specific album and track number.
Album and track numbers are used to form a unique ID for each bgm, allowing up to 64k different bgm tracks.
### &lt;sfx&gt; tag ###
**Syntax**: `<sfc>[album - integer],[track - integer],[filename - ogg]`
**Example**: `<sfc>0,0,myBgm.ogg`
Used to assign a sound effect (`.ogg` audio file) to a specific album and track number.
Album and track numbers are used to form a unique ID for each sound effect, allowing up to 64k different sound effects.
## Using conditions ##
To use conditions, add the condition's name at the start of the line. e.g:
`[myConditionName]<tile>...`
Conditions can only be applied to `<tile>` or `<background>` tags. When a condition is applied to a `<tile>` or `<background>` tag, that rule will only be used if the condition is met.
The first matching rule (in the order they are written in the `hires.txt` file) will be used. So conditional tiles MUST be placed before tiles with no conditions (for the same `tile data`+`palette data`) to have any effect.
You can also make it so multiple conditions must be met for a rule to be used by joining each condition name with a &:
`[cond1&cond2]<tile>...`
## Replacing audio in games ##
Audio replacement in HD packs in Mesen works in a similar fashion to the MSU-1 for the SNES. It adds a number of read/write registers in memory and they can be used to play OGG files specified via `<bgm>` and `<sfx>` tags.
`TO BE COMPLETED`.
### $4100/$3002: Playback Options ###
### $4101/$3012: Playback Control ###
### $4102/$3022: BGM Volume ###
### $4103/$3032: SFX Volume ###
### $4104/$3042: Album Number ###
### $4105/$3052: Play BGM Track ###
### $4106/$3062: Play SFX Track ###

168
Docs/content/tools/_index.md Normal file
View file

@ -0,0 +1,168 @@
---
title: Tools
weight: 3
chapter: false
---
<div class="imgBox right"><div>
<img src="/images/ToolsMenu.png" />
<span>Tools Menu</span>
</div></div>
## Netplay ##
### Hosting a game ###
<div class="imgBox"><div>
<img src="/images/NetplayHost.png" />
<span>Server Configuration</span>
</div></div>
**Server name**: This name will be shown to clients when they connect.
**Port**: The port used for the communication. Mesen will attempt to automatically port-forward this port on your router when you start the server -- if this fails, you will have to manually forward the port on your router to allow people outside of your LAN to connect to your server.
The other options on this screen have not been implemented yet and are disabled for now.
<div class="clear"></div>
### Connecting to a server ###
<div class="imgBox"><div>
<img src="/images/NetplayConnect.png" />
<span>Connect to...</span>
</div></div>
**Host**: The host name of the server you want to connect to. This is usually an IP address but can also be a domain name.
**Port**: The port to connect to -- this must match the `Port` value used by the server's host.
**Join as a spectator**: When enabled, you will join the server without taking control of a specific controller. An unlimited number of spectators can join a game, but only 4 people can take control of a controller.
Once you are connected to a server, you can select your controller via the **<kbd>Tools&rarr;Netplay&rarr;Select Controller</kbd>** menu.
## Movies ##
<div class="imgBox"><div>
<img src="/images/MovieRecordingOptions.png" />
<span>Movie Recording Options</span>
</div></div>
`Movies` are files that can be created by Mesen and played back within Mesen itself. They are essentially a recording of the events that occurred during recording. To record an actual video file, see [Video Recorder](#video-recorder).
When you start recording, a configuration dialog is shown that allows you to select a number of options.
* **Save to**: The location where the movie will be saved. Press the **Browse** button to change it.
* **Record from**: Selects where the recording should start:
* **Power on**: This will reset the game and start recording from the start. Your save data (.sav files) will be excluded from the movie file - after the reset, you will start the game as if it had never been run yet.
* **Power on, with save data**: This will reset the game and start recording from the start. Your save data (.sav files, etc.) will be included in the movie file.
* **Current state**: This will start recording from the current state -- in this case, the movie file will contain a save state.
* **Author**: The movie's author (optional) - this will be saved in the movie file.
* **Description**: A description of the movie's content (optional) - this will be saved in the movie file.
To play a movie file, select it via the **<kbd>Tools&rarr;Movies&rarr;Play</kbd>** command.
## Cheats ##
<div class="imgBox"><div>
<img src="/images/CheatList.png" />
<span>Cheats Window</span>
</div></div>
Mesen supports cheats in a number of different formats, including Game Genie and Pro Action Rocky codes.
It is also possible to import cheats from the built-in [Cheat Database](#from-the-cheat-database) or from [XML or CHT files](#from-xml-cht-files).
Select a game on the left to see all the cheats currently available for that game.
**To add a new cheat code**, click the `Add Cheat` button.
**To edit a cheat code**, double-click on it in the list.
**To delete a cheat code**, select it from the list and click the `Delete` button.
**To import cheats**, click the `Import` button.
**To export cheats to an XML file**, click the `Export` button.
**To disable a specific cheat**, uncheck it from the list.
**To disable all cheats**, check the `Disable all cheats` option.
<div class="clear"></div>
### Adding/Editing Cheats ###
<div class="imgBox"><div>
<img src="/images/EditCheat.png" />
<span>Edit Cheat</span>
</div></div>
When adding a cheat, you must first select the game to which it should be applied. By default, the game that is currently loaded will be selected.
You must give each cheat a name, which will be used to display it in the cheats list.
The `Code` section lets you enter the actual cheat -- select `Game Genie` for Game Genie codes.
If you want to create a custom code, select the `Custom` action.
When creating custom codes, the `Memory` / `Game Code` options select whether the code should be applied to a specific CPU address (`Memory`) or a specific offset in the PRG ROM (`Game Code`).
<div class="clear"></div>
### Importing Cheats ###
#### From the Cheat Database ####
<div class="imgBox"><div>
<img src="/images/CheatDbImport.png" />
<span>Import cheats from the built-in cheat database</span>
</div></div>
To import from the cheats database, click `Import` and select `From Cheat Database`.
In the next dialog, select the game for which you want to import cheats. You can type in the `Search` bar at the top to filter the game list. Once you've selected a game, press OK -- this will import all cheats for that game into the cheats list. You can then manually enable any cheat you want to use.
By default, the game that is currently loaded will be selected for you. Having no game selected when the dialog opens indicates that there are no built-in cheats available for the game that is currently running.
#### From XML/CHT files ####
To import cheats from external files (FCEUX's `.cht` files or Nestopia's `.xml` files), click `Import`, and select `From File (XML, CHT)`.
In the next dialog, select the file you want to import.
For FCEUX's `.cht` files, you will also need to select the game for which you are importing cheats for.
Once you're done, click `OK` -- the cheats will be imported and added to the cheats list.
## Sound Recorder ##
The sound recorder allows you to record uncompressed `.wav` files. The `.wav` file will use the exact same output settings as Mesen's [audio options](/configuration/audio.html) -- this means the sample rate will match Mesen's current sample rate, and that any sound modification (volume, panning, equalizer or effects) will also be applied to the `.wav` files.
To start recording, use the **<kbd>Tools&rarr;Sound Recorder&rarr;Record</kbd>** command.
To stop an on-going recording, use the **<kbd>Tools&rarr;Sound Recorder&rarr;Stop Recording</kbd>** command.
## Video Recorder ##
<div class="imgBox"><div>
<img src="/images/VideoRecording.png" />
<span>Video Recorder</span>
</div></div>
Much like the sound recorder, the video recorder allows you to record `.avi` files.
Before you start a recording, you can select where to save the `.avi` file and which video codec to use. All video codecs are lossless codecs -- the only reason to reduce the compression level to a lower level is to improve performance in the event your computer is having a hard time recording the video and running the emulation at its normal speed at the same time.
To start recording, use the **<kbd>Tools&rarr;Video Recorder&rarr;Record</kbd>** command.
To stop an on-going recording, use the **<kbd>Tools&rarr;Video Recorder&rarr;Stop Recording</kbd>** command.
## Log Window ##
<div class="imgBox"><div>
<img src="/images/LogWindow.png" />
<span>Log Window</span>
</div></div>
The Log Window displays a number of useful information -- mostly about the roms you load.
It is also sometimes used as a way to log errors or warnings.
## Debugger ##
See [Debugging Tools](/debugging.html)
## HD Pack Builder ##
See [HD Packs](/hdpacks.html)

197
Docs/static/css/custom.css Normal file
View file

@ -0,0 +1,197 @@
.blue { color: blue; }
.red { color: red; }
.green { color: green; }
.magenta { color: magenta; }
.gray { color: gray; }
a {
font-weight: 400;
}
#search-by {
color: #fff !important;
}
#search-by::-moz-placeholder {
color: #eee !important;
opacity: 1 !important;
}
#search-by::-webkit-input-placeholder {
color: #eee !important;
opacity: 1 !important;
}
nav#TableOfContents {
max-height: initial;
}
.toc {
border: 1px solid #999;
background-color: #FCFCFC;
color: black;
display: inline-block;
position: relative;
overflow: hidden;
}
.toc > div {
position: relative;
left: -10px;
}
ul > li > ul:only-child {
position: relative;
left: -40px;
background-color: #FCFCFC;
}
.progress ul > li > ul:only-child {
left: 0px;
}
.toc > div[data-level="3"] {
position: relative;
left: -80px;
}
h2 {
clear: both;
font-size: 2rem;
border-bottom: 1px solid #DDD;
}
h3{
font-size: 1.5rem;
border-bottom: 1px solid #DDD;
}
h4{
font-size: 1.20rem;
border-bottom: 1px solid #DDD;
}
ul {
margin-top: 0.5rem;
margin-bottom: 0.75rem;
}
p {
margin-bottom: 0.5rem;
}
pre {
background-color: #F6F6F6;
border: 1px solid #DDD;
padding: 2px;
margin-top: 0 !important;
}
code + span.copy-to-clipboard {
display: none;
}
pre code {
color: #666;
}
.hljs {
background-color: #F6F6F6;
color: #666;
}
.hljs-subst, .hljs-variable, .hljs-template-tag, .hljs-template-variable{
color: #6a9e97
}
.hljs-attribute, .hljs-code, .hljs-selector-id {
color: #92649b
}
.hljs-comment {
color: #369635;
}
.hljs-title, .hljs-name {
color: #92649b;
}
pre .copy-to-clipboard {
background-color: #E9E9E9;
}
pre .copy-to-clipboard:hover {
background-color: #FFF;
}
.clear {
clear: both;
}
.imgBox {
clear:both;
float:right;
padding-left: 10px;
background: white;
z-index: 1;
position: relative;
}
.imgBox > div {
padding:5px;
border:1px solid #aaa;
background-color:#F9F9F9;
}
.imgBox > div img {
margin:0 !important;
border:1px solid #DDD;
}
.imgBox.inline {
float:none;
text-align: center;
}
.imgBox.inline > div {
display: inline-block;
}
@media (max-width: 1700px) {
.imgBox {
float:none;
text-align: center;
}
.imgBox > div {
display: inline-block;
}
}
section#shortcuts > h3 {
font-weight: bold !important;
color: #DDD !important;
}
.imgBox.right {
float:right;
}
.imgBox.right > div {
display:block;
}
@media (max-width: 1000px) {
#body #breadcrumbs {
width: 100%;
}
h1 {
font-size: 2rem;
}
h2 {
font-size: 1.5rem;
}
h3 {
font-size: 1.3rem;
}
h4 {
font-size: 1.1rem;
}
.imgBox.right {
float:none;
text-align: center;
}
.imgBox.right > div {
display: inline-block;
}
}

BIN
Docs/static/images/Assembler.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
Docs/static/images/AudioOptions_Advanced.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 9.3 KiB

BIN
Docs/static/images/AudioOptions_Effects.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 9.5 KiB

BIN
Docs/static/images/AudioOptions_Equalizer.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
Docs/static/images/AudioOptions_General.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 8.8 KiB

BIN
Docs/static/images/AudioOptions_Panning.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 9.8 KiB

BIN
Docs/static/images/AudioOptions_Volume.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 9.8 KiB

BIN
Docs/static/images/BreakpointList.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.5 KiB

BIN
Docs/static/images/CallStack.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 4.5 KiB

BIN
Docs/static/images/CheatDbImport.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
Docs/static/images/CheatFinder.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 7.1 KiB

BIN
Docs/static/images/CheatList.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 19 KiB

BIN
Docs/static/images/ChrViewer.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 43 KiB

BIN
Docs/static/images/CodeWindow.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 43 KiB

BIN
Docs/static/images/CommandLineOptions.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
Docs/static/images/ConfigWizard.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
Docs/static/images/CpuPpuMapping.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.7 KiB

BIN
Docs/static/images/DebuggerWindow.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 78 KiB

BIN
Docs/static/images/EditBreakpoint.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 9 KiB

BIN
Docs/static/images/EditCheat.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.4 KiB

BIN
Docs/static/images/EditCodeExample.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
Docs/static/images/EditLabel.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 3.8 KiB

BIN
Docs/static/images/EmulationSettings_Advanced.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
Docs/static/images/EmulationSettings_General.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 7.4 KiB

BIN
Docs/static/images/EmulationSettings_Overclocking.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
Docs/static/images/EmulationStatus.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
Docs/static/images/FdsGameMenu.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.6 KiB

BIN
Docs/static/images/FunctionList.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
Docs/static/images/GameMenu.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 3.5 KiB

BIN
Docs/static/images/GameSelectionScreen.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 97 KiB

BIN
Docs/static/images/HdPackBuilder.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
Docs/static/images/HeaderEditor.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
Docs/static/images/HexEditor.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 27 KiB

BIN
Docs/static/images/HexEditorTbl.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
Docs/static/images/InputButtonSetup.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.7 KiB

BIN
Docs/static/images/InputOptions_Advanced.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.4 KiB

BIN
Docs/static/images/InputOptions_Controller.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
Docs/static/images/InputOptions_General.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.9 KiB

BIN
Docs/static/images/LabelList.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
Docs/static/images/LogWindow.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
Docs/static/images/MemoryAccessCounters.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
Docs/static/images/MesenIcon.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.7 KiB

BIN
Docs/static/images/MovieRecordingOptions.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 8.4 KiB

BIN
Docs/static/images/NametableViewer.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
Docs/static/images/NetplayConnect.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 2.6 KiB

BIN
Docs/static/images/NetplayHost.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 4.5 KiB

BIN
Docs/static/images/NsfPlayer.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
Docs/static/images/OptionsMenu.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 7 KiB

BIN
Docs/static/images/PaletteViewer.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
Docs/static/images/Preferences_Advanced.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
Docs/static/images/Preferences_FoldersFiles.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
Docs/static/images/Preferences_General.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
Docs/static/images/Preferences_Nsf.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.1 KiB

BIN
Docs/static/images/Preferences_SaveData.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 9.3 KiB

BIN
Docs/static/images/Preferences_ShortcutKeys.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
Docs/static/images/Profiler.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
Docs/static/images/ScriptWindow.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
Docs/static/images/SpriteViewer.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
Docs/static/images/ToolsMenu.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 8.6 KiB

BIN
Docs/static/images/TraceLogger.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 68 KiB

BIN
Docs/static/images/VideoOptions_Advanced.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
Docs/static/images/VideoOptions_General.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
Docs/static/images/VideoOptions_Overscan.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 8 KiB

BIN
Docs/static/images/VideoOptions_Palette.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
Docs/static/images/VideoOptions_Picture.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
Docs/static/images/VideoRecording.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 4.3 KiB

BIN
Docs/static/images/VsGameMenu.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.6 KiB

Some files were not shown because too many files have changed in this diff Show more