Geolith
-------
Geolith is a highly accurate emulator for the Neo Geo AES and MVS.

This emulator supports TerraOnion's .NEO file format only.

BIOS files from a recent MAME set are required:
 - aes.zip for Neo Geo AES (Home Console)
 - neogeo.zip for Neo Geo MVS (Arcade) and Unibios

This repository lives at https://gitlab.com/jgemu/geolith

Compiling
---------
Make sure you have The Jolly Good API's header files installed. If you did
not install them, you will be required to include their path in CFLAGS.

Options:
  DISABLE_MODULE - Set to a non-zero value to disable building the module.
  ENABLE_STATIC_JG - Set to a non-zero value to build a static JG archive.
  USE_EXTERNAL_MINIZ -  Set non-zero to use an external miniz
  USE_VENDORED_SPEEXDSP - Set to a non-zero value to use vendored SpeexDSP

Linux:
  make

macOS:
  make

BSD:
  gmake

Windows (MSYS2):
  make

Cross Compile:
(For example compiling on Linux for MinGW)
  AR=x86_64-w64-mingw32-ar \
  CC=x86_64-w64-mingw32-cc \
  PKG_CONFIG=x86_64-w64-mingw32-pkg-config \
  STRIP=x86_64-w64-mingw32-strip \
  make

The build will be output to "geolith/". This directory may be used as is
locally by copying it to your local "cores" directory, or may be installed
system-wide using the "install" target specified in the Makefile.

Input Devices
-------------
Geolith supports the following input devices:

Neo Geo Joystick
Neo Geo Mahjong Controller
Multiplayer Extension Board (NEO-FTC1B, 4 Player)
V-Liner

Settings
--------
input = 0
0 = Auto, 1 = Neo Geo Joysticks, 2 = Mahjong, 3 = 4-Player (AS/JP MVS)

system = 0
0 = AES (Console), 1 = MVS (Arcade), 2 = Universe BIOS

region = 0
0 = US, 1 = JP, 2 = AS, 3 = EU

freeplay = 0
0 = Off, 1 = On

settingmode = 0
0 = Off, 1 = On

aspect = 0
0 = 1:1 PAR, 1 = 45:44 PAR, 2 = 4:3 DAR

overscan_t = 2
0 = 0, 1 = 4, 2 = 8, 3 = 12, 4 = 16

overscan_b = 2
0 = 0, 1 = 4, 2 = 8, 3 = 12, 4 = 16

overscan_l = 2
0 = 0, 1 = 4, 2 = 8, 3 = 12, 4 = 16

overscan_r = 2
0 = 0, 1 = 4, 2 = 8, 3 = 12, 4 = 16

adpcm_wrap = 1
0 = Off, 1 = On

Auxiliary Files
---------------
System ROM collections (BIOS et al) in the form of a .zip file may be loaded as
auxiliary files.

Compatibility
-------------
Geolith is compatible with 100% of the commercially released Neo Geo AES and
MVS libraries. Most games work in both modes, but some require MVS mode.

All bootlegs and hacks from the MAME set are compatible, the majority of which
require being run in MVS mode. Other bootlegs and hacks not in the MAME set may
be compatible if correctly converted to the .NEO format.

Some MVS releases will exhibit glitches when run on an AES BIOS. Home Console
releases are preferred when running in AES mode.

Some early prototypes are not currently possible to emulate, pending new dumps
or new information:
  Stakes Winner (early development board) - Missing data from SRAM chip

Dedicated JAMMA PCB and Neo Geo CD systems are not currently supported.
PAL mode is not currently supported.

The special inputs for Irritating Maze are not yet supported. It is possible to
play Irritating Maze using the Universe BIOS with a cheat enabled for joystick
controls.

Accuracy/Caveats
----------------
Geolith's CPUs are emulated at instruction level granularity and are very
tightly synced to each other as well as the LSPC (video) and YM2610 (sound).
Video related events are timed with a "best effort" approach based on available
documentation, with future original hardware research on the agenda. The longer
term goal is to have completely cycle accurate video rendering, but for now,
things are emulated accurately enough that all games are fully playable with
only very minor differences from real hardware, and no known major bugs.

Porting
-------
Geolith was written in standards compliant ISO C11 and should be extremely
portable. Though it was written for The Jolly Good API, it was done in a
manner that allows it to be used easily in multi-emulator frameworks or
standalone binaries for many potential platforms. If a new fork is created
with significant modifications, a clear indication that it is not officially
supported would be courteous. Please be an honest person and respect the
licenses that apply to the software.

Contributing
------------
Any contributions should respect the coding style and the direction and goals
of this emulator. All code should be placed under a permissive license (BSD,
MIT, etc). Changes made for portability or speed should be as generic as
possible, and any preprocessor directives for platform-specific code should be
avoided at all costs in the interest of keeping the emulator core clean,
maintainable, and free of regressions.

Copyright
---------
Geolith (BSD-3-Clause)
  Copyright (c) 2022-2025 Rupert Carmichael
  See LICENSE

Jolly Good Z80 (MIT)
  Copyright (c) 2019 Nicolas Allemand
  Copyright (c) 2020-2022 Rupert Carmichael
  Copyright (c) 2022 rofl0r
  See src/z80/LICENSE

miniz (MIT)
  Copyright 2013-2014 RAD Game Tools and Valve Software
  Copyright 2010-2014 Rich Geldreich and Tenacious Software LLC
  See deps/miniz/miniz.c (https://github.com/richgel999/miniz)

Musashi (MIT)
  Copyright (c) 1998-2019 Karl Stenerud
  See src/m68k/readme.txt (https://github.com/kstenerud/Musashi)

Speex Resampler (BSD-3-Clause)
  Copyright (c) 2003, 2007, 2008 Xiph.org Foundation
  See source files in deps/speex/ (https://github.com/xiph/speexdsp)

YMFM-C (BSD-3-Clause)
  Copyright (c) 2021 Aaron Giles
  Copyright (c) 2022 Rupert Carmichael
  See source files in src/ymfm

Extra Credits
-------------
This emulator could not have been written without the amazing documentation
available at The NeoGeo Development Wiki (https://wiki.neogeodev.org) as well
as copious research and effort from the FinalBurn Neo and MAME projects.

This project began life as a fork of GnGeo 0.8.1. All original components
were removed or replaced as the project progressed, with the resulting codebase
being entirely new, with all new code written under the BSD 3-Clause license.
A special thanks goes out to Mathieu Peponas who both created the original
GnGeo emulator, and also approved the distribution of this new work as a whole
with new licensing. This resolves the "Ship of Theseus" question.

Trivia
------
The first game ever completed on this emulator was Blazing Star.
