MY NES
------
A Nintendo Entertainment System / Family Computer (Nes/Famicom) Emulator written in C#.

Copyright © Alaa Ibrahim Hadid 2009 - 2022
All rights reserved.

Email: alaahadidfreewares@gmail.com

My Nes Official Repository: <https://github.com/alaahadid/My-Nes>
My Nes Official Wiki: <https://github.com/alaahadid/My-Nes/wiki>
My Nes Issues Board (please report bugs here): <https://github.com/alaahadid/My-Nes/issues>
My Nes Contact Email: <mailto:alaahadidfreewares@gmail.com>

Introduction
-------------
My Nes is A Nintendo Entertainment System / Family Computer (Nes/Famicom) emulator written in C#. 
An open source .net freeware, licensed under the GNU GENERAL PUBLIC LICENSE; Version 3, 29 June 2007.

The main goal of My Nes is to be as accurate as possible and brings the best game play experince possible.

My Nes can pass all basic nes tests that test nes hardware behaviors, such as cpu 6502 instructions, 
ppu timing .... etc. However, My Nes pass most of these tests (known at development time of current version) 
without any kind of work-arounds (changing some code to make a test pass), by emulating the exact hardware behavior.

My Nes Able to decode nes colors without the need of using palette, includes gray scale and emphasize. For NTSC, PALB and DENDY.
Expect real NES COLORS as they should be !!
Also the exact audio mixer as descriped at http://wiki.nesdev.com/w/index.php/APU_Mixer (i.e. low-pass and high-pass filters) is implemented.
Video and audio outputs are configured carefully to produce video and sound as accurate as possible.

If you are looking for an easy-to-use Nes emulator, meant for game play expericne and provides accuracy that very close to the real hardware, 
My Nes is a one that worth a try !

Features And Specification
--------------------------
- My Nes uses simple GUI (Graphical User Interface) which allows to change game, configure emulation directly 
  and as simple as possible.
- My Nes include built-in Launcher which can be used to organize games, it can provide detailed information about
  games, also it can record user data such as rating, play time etc
- My Nes Uses NesCart DB to show and use accurate game information.
- My Nes include built-in rendering engine that allows to switch between renderers easily and effectively. This can 
  help to select the proper renderer that suits up your system, for example, if the SlimDX video renderer run with 
  problems with you machine, simply switch to SDL2 video renderer, which may run smooth in you pc. 
- All useful video options are included, such as running the emu in windowed or fullscreen mode with keep aspect ratio 
  turned on or off.
- Ability to save snapshots of current game.
- Ability to record sound for each game.
- Save and load state ability.
- My Nes runs very fast in low end machines (such as low end laptops, old pcs ..etc), My Nes is tested in old machines, 
  both in Windows and runs perfectly 60 fps.

### My Nes Core Features

 Accuracy, My Nes pass almost all known nes tests by emulating the real hardware behaviors without any kind of emulation 
  hack.
 Multi-threaded Emulator, the emulation process run in thread separated from renderer threads. 
  This may improve performance especially with multi core cpus. 

### My Nes Emulation Specification

- CPU 6502: All CPU 6502 instructions implemented including the so called illegal opcodes.
  Exact interrupt timings like interrupt check before the last instruction behavior.
- APU: all Nes 5 sound channels, MMC5 external sound channels and VRC6 external sound channels.
  Emulates the APU-CPU write/read behaviors (exact apu clock timing)
  Built-In Mixer
  Lookup table Mixer as descriped at http://wiki.nesdev.com/w/index.php/APU_Mixer 
  low-pass and high-pass filters are implemented which exists in the real hardware, Thus, the audio process works like this:
  EMU Clocks at ~1.79 MHz, audio outputs at ~447443.25 Hz => 
  high-pass filter at 90 Hz => 
  high-pass filter at 440 Hz => 
  low-pass filter at 14 kHz =>
  pick samples at audio playback frequency (i.e. 44100 Hz/48000 Hz ..etc) then write samples into playback buffer (i.e. play sound).
- PPU: Picture Processor Unit as described in the wiki docs http://wiki.nesdev.com/w/index.php/PPU_rendering 
  is implemented (as close as possible) with exact timing, also ppu vram-bus and io-bus are implemented as well.
- Colors: Ability to decode nes colors without the need of using palette, includes gray scale and emphasize. For NTSC, PALB and DENDY.
- TV Formats: NTSC, PALB and DENDY. 
- Video Output: Resolution can be upscaled from res 256 x 240 nes basic till 1920 x 1080 Full HD and even higher resolutions. 
  Uses Resolution-Blocks-Upscaler method <https://github.com/alaahadid/Resolution-Blocks-Upscaler>.
- Sound Playback: playback frequency can be 22050 Hz, 44100 Hz or 48000 HZ. 
  Bit rate fixed to 16 bit, channels can be Mono or Stereo. Includes built-in wave recorder, records sound with the same playback settings (i.e. Stereo, Mono ..etc).
  Ability to render audio in Stereo-Nes mode, which is a hack allows to adjust pan of audio channels in stereo. Works only with the internal nes 5 channels.
- Mappers And Boards: Implement about 97% of known and documented mappers
- Controllers: 4 players joypads, each joypad is playable through Keyboard, Joystick or XBox360 Game Controller (XInput). 
  Game Genie is implemented as well.

System Requirements And Installation
------------------------------------
Usually My Nes comes in portable package, which can be installed simply by extracting the content of that package 
anywhere in your machine.
Note that My Nes save settings and user files (such as states, snapshots, sound records ...etc) at the documents.
In order to run My Nes correctly in your machine, please make sure that your machine meets up these requirements:

- My Nes can run at any version of windows that can run .net framework 4, such as Windows 7, 8, 8.1 and 10.
- .Net Framework version 4.8 is required.
- Latest DirectX package from Microsoft.
- Latest C++ Runtime package from Microsoft. (Try latest, if My Nes doensn't work, installing older version of this package may work.)
- CPU: 2400 MHz or faster, multicore cpu is recommended for better performance. My Nes is built for x86 cpus, 
  but it should run without problems with x64 cpus (tested and runs perfectly)
- RAM: My Nes usually uses about 30 to 60 MB ram. When launcher is used, it may use up to 200 MB. In other words, 
  since Windows is running perfectly in your machine, you should not worry about ram at all when using My Nes.


IMPORTANT NOTES:
----------------
Each renderer (for video and audio) is carefully configured for best quality and performance that a renderer can produce.

- Slimdx renderers render using Direct3d9 for video and DirectSound for sound.
  Known issues with these renderers:
. Sometimes the video drops into 30 fps even though there is no game loaded, the cause of this issue is unknown in this time. Restarting My Nes may fix this problem, but If it remains, there is no choice but to switch into SDL2 Video.
. Sometimes SlimDX video renderer makes My Nes craches (when switching into fullscreen for example). Sorry for this bug, still have no idea what's the problem excatly... still working on fixing it though, all you need to do is to restart My Nes and try again to run the game.

- SDL2 renderers render using SDL2 library. The video renderer can be set to direct3d or opengl driver. Also audio device/driver can be switched in SDL2 settings.

There is no big difference between these renderers, since renderers in fact just act as outputs presenters. The only difference you may notice is with performance, you need to carefully choose and configure My Nes to run smoothly in your machine.
Also you can mix renderers, for example, you can use SlimDX for video and SDL2 for sound... Renderers can be switched anytime from the main menu, note that changing a renderer requires My Nes to restart to take effect.
As default, My Nes is set to use SDL2 for video and SlimDX for sound rendering. After tests, this is the best performance you can get from My Nes.

TROUBLES SHOOTING:
------------------
- My Nes doesn't work:
Please make sure that these packages are installed in pc:
- .Net framework 4.8
- C++ Runtime (Try latest, if My Nes doensn't work, installing older version of this package may work.)

If the problem isn't solved, please try to install SlimDX latest runtime, one can be found here: <https://code.google.com/archive/p/slimdx/downloads> (SlimDX Runtime .NET 4.0 x86 (January 2012).msi).

- Error (about cannot open archive for example) when trying to open a .nes game
If that happens, you need to locate the settings file in:

Documents>MyNes

And delete them all except folders. Files are: controls.mnc, emusettings.ini, renderersettings.ini, sdlsettings.ini and winsettings.ini.

This will reset all settings into default.

- Some games doesn't work
Please use Hard Reset (F4) to reset the emulation, happen sometimes when changing games. If the game stil doesn't work, that's mean it is a not-implemented mapper issue or emulation bug. Reporting the game problem to the <https://github.com/alaahadid/My-Nes/issues> will be appreciated.

- My Nes may fail to launch with SDL2 video renderer, or just "White Screen".
If that happens, you need to locate the settings file in:

Documents>MyNes>sdlsettings.ini

Open that file then edit the line (set it to):
"Video_Driver=opengl" or "Video_Driver=direct3d" then try again.
direct3d: is the direct3d driver
opengl: is the opengl driver

If both drivers doesn't work, there is no choice but to switch into SlimDX video renderer.

- There is no sound whith SDL2 Audio.
Please try to change audio device selection in SDL2 Settings window.

If that doesn't work, you need to locate the settings file in:

Documents>MyNes>sdlsettings.ini

Open that file then find the line :
"Audio_Device_Index=0"
This is the audio device index, 0 is the first audio device, 1 is the second ...etc
Can be set to any "Enabled" audio device, please set the index to the default audio device in Windows audio settings.

If that doesn't work, there is no choice but to switch into SlimDX audio renderer.

NOTES:
------
- If a Xbox Controller is connected, it will be assigned automatically (ready to play, plug it before starting My Nes): X Controller player 1 for nes player 1, player 2 for nes player 2... player 4 for nes player 4.

- If a controller is assigned, then it is disconnected, My Nes will automatically switch back into keyboard.

- You can use Keyboard, Joystick or Xbox 360 Controller for emulation shortucts.

- When you use the launcher to launch a game, then you want the launcher to return, press F1/Escape to shutdown the emulation. This should bring up the launcher dialog back.

- For better experience, please make sure that audio frequency value (Audio>Frequency) matches the sound output frequency in your pc.
  You can set custom frequency value in the settings: 
  go to \Documents\MyNes, edit renderersettings.ini, change line: Audio_Frequency=48000 while 48000 is audio frequency 
  then save the file. 

- Video Output: Resolution can be upscaled from res 256 x 240 nes basic till 1920 x 1080 Full HD and even higher resolutions. 
  Resolution rendering is done in real time, directly after producing video output of quality 256 x 240. The result is creystal clear next to real tv video rendering.
  Resolution upscale can be disabled from Main Menu > Resolution Upscale. The image quality also depends on filter used for scaling from selected res: linear or point.
  Custom resolution can be set by locating the settings file in:
  `Documents>MyNes>renderersettings.ini`
  Open that file then find the lines :
  `Vid_Res_W=640`
  `Vid_Res_H=480`
  Change `Vid_Res_W=640` to the width of any resolution needed (for example `Vid_Res_W=1920`) and `Vid_Res_H=480` to the height of the new res (for example `Vid_Res_H=1080`).
  Wrong resolution results distorted images. 

  **My Nes can renderer resolution higher than full-hd but requires very powerfull pc. Custom resolution need to be set for reolutions higher than 1920 x 1080**

My Nes Launcher
---------------
- First Time Launching The Launcher

When you open the Launcher for the first time, it will ask you create new database.

To open the Launcher window, go to File>Launcher or press CTRL+C.
In the first Launcher run:

A window labeled "Create Database" will be opened, enter the new database name in the Database name field.
You can change the database file location via ".." button. The default location is inside My Nes folder.
Generate entries from NesCartDB: enabling this option will make the Launcher generate entries from NesCartDB. 
That's mean all games listed in NesCartDB will be added as entries in the new created database.



- On NesCartDB generating:

If you enabled the option Generate entries from NesCartDB, the Launcher will start the generate process. 
This may take few minutes depending on pc speed and NesCartDB size. When done, the Launcher will be opened with all 
NesCartDB games listed. 
This is useful to fill the table with all available game information from NesCartDB such as game Developer, 
game Publisher ...etc.

If you choose not to generate the NesCartDB entries, the Launcher will be opened immediately with empty list. 
You'll need to add or assign files later to use the Launcher.



- Adding And Assigning Files

After you run the Launcher for the first time, you'll need to add (or assign) files to be able to play the games 
in My Nes. Whether you choose to generate NesCartDB entries or not, you should use one of the following buttons:

 ASSIGN button: means assign or add files using the FOLDER SCAN. Folder scan means My Nes will search specified 
  folders for files then assign them or add them to the database.
 ADD button: means assign or add files by opening and choosing them one by one.

* ASSIGN:

 Click the ASSIGN button on the toolbar.
 In the assign window that should be appeared, use the Add button to add folders to the folders to scan list. 
  These folders should be include the rom files (supported file types are '.nes', '.7z', '.zip' and 'rar'). 
  Use Remove button to remove folder(s) from the list.
 Include sub-folders in search: enabling this will force the Launcher to search all folders inside the folders 
  in the list for file. Otherwise, only files in the folders in the list will be taken.
 Add files not found in database as new entries: this is the most important option. 

  When the Launcher search for files, it first look for entry match the SHA1 of that file inside the database. 
  If it matchs, this entry get updated (ASSIGNED) otherwise, that file considered as new entry if this option 
  (Add files not found in database as new entries) is enabled. Otherwise this file get ignored.
  That's the difference between ASSIGN and ADD. 

  The entry considered as a match only if the SHA1 is matched and that entry is generated using the NesCartDB.

 Update entries already assigned: This option is important for some cases.

  As above, when the Launcher search for files, it first look for an entry match the SHA1 of that file inside the 
  database. If it match, this entry get updated (ASSIGNED). This work only when the SHA1 is matched and that entry 
  is generated using the NesCartDB .
  But in case there is no entry match those conditions (or no entry generated using NesCartDB) the Launcher will use 
  the file path to locate the match. If an entry has the same path (or the same file) this entry get updated (Size only) 
  only if this option (Update entries already assigned) is enabled. Otherwise this file get ignored.

  This option should be disabled when: your roms collection include same file (files with the same SHA1) compressed with 
  different names. For example, you have Super Mario Bros game file compressed in 2 archive files: SMP.zip and SMP1.zip.

* ADD:

 Click the ADD button on the toolbar.
 Choose the files you like to assign or add then click open.
 This work as same as ASSIGN (see ASSIGN section above) with these settings:

  Include sub-folders in search: is DISABLED.
  Add files not found in database as new entries: is ENABLED
  Update entries already assigned: is DISABLED.

Now the collection is ready. Double click on and entry to play that game, or click on the PLAY button on the left 
toolbar to play that game as well. Also you can use the Enter (Return) button on your keyboard.

* NOTES

 The ASSIGN or ADD process may take long time, it may take hours if the files you use are compressed. 
  When starting the ASSIGN/ADD process, keep that in mind.
 Make sure your roms collection never include this case: your roms collection include same file (files with the 
  same SHA1) compressed with different names. For example, you have Super Mario Bros game file compressed in 2 archive 
  files: SMP.zip and SMP1.zip. This case may cause mistakes in entries.
 After finishing the ASSIGN/ADD process, the entries in the table will be marked:
  X : this entry has no file assigned or the file is missing. (This entry cannot be played)
  cart like icon : this entry has file assigned and that file is exist. (This entry can be played)



- Detect Info Files

In order to use the Info Tabs (see Navigating for more), you'll need to attach info file(s) for each entry. 
For example, in order to view snapshots of a game, you need to select the snapshots you want for that game then 
to assign them. The Launcher is capable of doing this automatically, and this process called DETECT.

 In the main toolbar of the Launcher window, click DETECT button.
 Then the Detect Mode Selection will be opened for you. Select the mode you want to detect files for. 
  For example, choosing Snapshots will detect snapshot files and set them for the games.
 Use Add button to add folder(s) which include the snapshot files. It's a good idea to use the Snapshots folder 
  of My Nes (see Paths)
 In the Extensions to use, enter the image file type extension(s) to use spitted with ';,'. This can be used to 
  include extension or to exclude an extension from the search.
 Activate Include subfolders in search if you want to search the sub folders of folders in the list.
 Don't assign same file to more than one entry: this option will force the search engine not to assign a file to 
  more than one entry if match. This may improve speed but may lose detects especially if a game have more than one 
  snapshot.
 Use entry name instead of entry file name: normally the search engine uses the entry file name to compare it with 
  the searched file name. If the entry has no file assigned, the entry name is used instead (to compare with the 
  searched file name of course).
 This option force the engine to use the entry name always, even the entry has a file assigned or not.
 Use entry name when the path is not valid: same of the above option:  normally the search engine uses the entry 
  file name to compare it with the searched file name. If the entry has no file assigned, the entry name is used 
  instead (to compare with the searched file name of course) only if this option is enabled. If this option is disabled, 
  this entry get ignored (no search applied to it).
  Search mode: The most important option, effect the search result slightly. You should choose the search mode carefully 
  depending on entries and snapshot files. 
  The modes are:
  
   Search mode Entry in file: In this mode, the search engine will look for the entry name (name or file name, here will 
   call it name) inside the searched file name. For example, let's say we have this entry name "Super Mario Bros" 
   and this snapshot file "Super Mario Bros Snap 1". In this mode, this is a match because of the "Super Mario Bros" 
   is included in "Super Mario Bros Snap 1". Thus, choosing this mode will be wise if the snapshots file names are 
   larger (in length) than the entry names/file names.
   
   Search mode file in Entry: In this mode, the search engine will look for the searched file inside the entry name. 
   For example, let's say we have this entry name "Super Mario Bros" and this snapshot file "Super Mario Bros Snap 1". 
   In this mode, this is NOT a match because of the "Super Mario Bros" does NOT include "Super Mario Bros Snap 1". 
   Thus, choosing this mode will be wise if the snapshots file names are smaller (in length) than the entry names/file 
   names.
  
   Search mode both: This mode is not recommended although it's nice and easier. This mode will make the search engine 
   to decide which mode of the previous modes to use. Generally, this may cause errors in many cases.

 Clear old detect files for entry: Indicates if the search engine should clear previously detected snapshot files that 
  assigned to the entries first.
 One file per entry: this may understood as same as Don't assign same file to more than one entry but it is not the 
  same. In this option, the entry take one snapshot file only for an entry but that file will STILL be available for 
  other entries. While the option Don't assign same file to more than one entry is meant to set the snapshot file to 
  one entry then that snapshot file get dropped from the search list and won't be used again.
 Match case: Indicates if the search engine should care about case: for example, if Match case is enabled, "Car" will 
  be treated different than "car". Otherwise "Car" and "car" will be treated the same.
 Match word: Indicates if the search engine would use word match instead of char match. For example if you search for 
  "Car" inside "Cartty", with is option DISABLED this is a match because of "Car" is included inside "Carttly". While 
  this is not a match when the Match word is not enabled because of the word "Car" doesn't match "Carttly".
  Another example is searching "car" inside "my car is nice", in this case Match word option has no effect and always 
  match!
 Text search type: The most important option too, effect the search result slightly. You should choose the text search 
  type carefully depending on entries and snapshot files (here will assume the search mode is Entry in file, 
  see step 10):
   
   Start with: this means the searched file name should be started with the entry name. Example: "Super Mario Bros" is 
   started with "Super Mario" thus this is a match while "Mario Bros" will considered as not match.

   Contains: this means the searched file name should contains the entry name. Example: "Super Mario Bros" 
   contain "Super Mario" and "Mario Bros" thus both words considered as a match.
  
   Ends with: this means the searched file name should be ended with the entry name. Example: "Super Mario Bros" 
   is ended with "Mario Bros" thus this is a match while "Super Mario" will be considered as not match.
 After choosing the right settings, click Start button. The search progress should take only few minutes 
  (maybe more or less). After that, you can test the result by selecting an entry. The Info Tabs should show the 
  detected files (snapshots for this tutorial)

* NOTES

 The search progress may take minutes, more or less depending on games collection.
 The previous tutorial was about Snapshots. This work the same for covers, info and Manuals.
 You can repeat the DETECT process as many times as you like with different settings. You may want to enable 
  Clear old detect files for entry option.
 It's a good idea to use the Snapshots folder of My Nes (see Paths ) since My Nes save snapshots with formula
  <GameName>_<SnapNumber> (Example: Super Mario Bros_0.jpg) and thus it can be detected easily.


- Search The Database

One of the important thing you may use is the search especially with huge games collection. The Launcher contain 2 
kind of search: Quick search and the Advanced Search.

The Quick Search:

In the main toolbar of the Launcher window, enter the game name you want to search for in the small text box, wait for 
few seconds then the search result should be appeared.
In this mode, the search parameters are: Search for game name, using Contain condition, Match case is off and Match 
word is off. For details about these parameters see below.

The Advanced Search:

Search for games using more advanced options. To search using this mode:

 Click on Find button on the toolbar of the Launcher window (See Navigating).
 The search window should be appeared, in the Find what field, enter the search word. It may be a name or number 
  depending on what you are looking for.
 Enable the Case sensitive if you like to use Case sensitive in search. ("Car" and "car" have different mean if 
  Case sensitive is active otherwise it will be treated the same)
 Search by: choose the column you want to use for search. It can be name, board mapper, board type ....etc.
 Condition: choose the search condition. Note that the condition get updated depending on the Search by selection.
  For example, if you choose Search by name then the condition will be for texts, while choosing Search by board mapper 
  will make the conditions for numbers. See tables below for condition types.
 Click on Find button to start the search.

Conditions for text search: 

(The search word is the word you enter in Find what field. The search target is the word that get searched)

 Condition           | Description
---------------------+----------------------------------------------------------------------------
 Contains            | The search word should be contained in the target word.
---------------------+----------------------------------------------------------------------------
 Does not contain    | The search word should not be contained in the target word.
---------------------+----------------------------------------------------------------------------
 Is                  | The search word should be as same as the target word. Just like equal mark.
---------------------+----------------------------------------------------------------------------
 In not              | The search word should be different than target word. Just like not equal.
---------------------+----------------------------------------------------------------------------
 Starts with         | The target word should be started with the search word.
---------------------+----------------------------------------------------------------------------
 Does not start with | The target word should not be started with the search word.
---------------------+----------------------------------------------------------------------------
 Ends with           | The target word should be ended with the search word.
---------------------+----------------------------------------------------------------------------
 Does not end with   | The target word should not be ended with the search word.
---------------------+----------------------------------------------------------------------------

Conditions for number search:

(The search number is the number you enter in Find what field. The search target number is the number that get searched)

 Condition        | Description
-------------- ---+--------------------------------------------------------------------------
 Equal            | The search number should equal the target number. "= "
-------------- ---+--------------------------------------------------------------------------
 Does Not Equal   | The search number should not equal the target number. "!= "
-------------- ---+--------------------------------------------------------------------------
 Larger           | The target number should be larger than the search number. ">"
-------------- ---+--------------------------------------------------------------------------
 Equal or larger  | The target number should equal or be larger than the search number. ">= "
-------------- ---+--------------------------------------------------------------------------
 Smaller          | The target number should be smaller than the search number. "<"
-------------- ---+--------------------------------------------------------------------------
 Equal or smaller | The target number should equal or be smaller than the search number. "<= "
-------------- ---+--------------------------------------------------------------------------

* NOTE

Search never effect the database, also can be applied on filter chosen.


Copyright Notice
--------------------------------------------------------------------------------------------------
Please read the file "Copyright Notice.txt" or see the about box in MyNes for more details.

Support
--------------------------------------------------------------------------------------------------
My Nes Official Repository: <https://github.com/alaahadid/My-Nes>
My Nes Official Wiki: <https://github.com/alaahadid/My-Nes/wiki>
My Nes Issues Board (please report bugs here): <https://github.com/alaahadid/My-Nes/issues>
My Nes Contact Email: <mailto:alaahadidfreewares@gmail.com>


END OF README.
--------------------------------------------------------------------------------------------------