                          Digital Distortion EmuWeb
                                Version 0.92
                           Release date: 2025-09-20

                                     by

                                Eric Oulashin
                          Sysop of Digital Distortion
                  BBS internet address: digitaldistortionbbs.com
                     Alternate address: digdist.synchro.net
                        Email: eric.oulashin@gmail.com



This file describes the Digital Distortion EmuWeb.

Contents
========
1. Disclaimer
2. Introduction
3. Installation & Setup
4. Configuration file options
5. Synchronet's web root directory setting
6. Metadata
7. Windows: Downloading 3rd-party crc32, sha1sum, and md5sum utilities
8. Notes


1. Disclaimer
=============
I cannot guarantee that this script is 100% free of bugs.  However, I have
tested it, and I used it often during development, so I have some confidence
that there are no serious issues with it (at least, none that I have seen).

I have tested this in Linux (where I run my BBS); Windows testing has not been
extensively tested, but it should work basically the same.

This is a pre-v1.0 release; as such, there are things I think can be improved.
One thing I would like to improve is metadata matching for games. Also, metadata
matching is currently fairly slow.


2. Introduction
===============
Digital Distortion EmuWeb (henceforth referred to as simply EmuWeb) is a web
front-end for EmulatorJS, a JavaScript engine that enables emulating old game
consoles & some early computers in a web browser. EmulatorJS is, in turn, a
front-end for RetroArch, a popular emulation engine. You can read more about
EmulatorJS on their web site:
https://emulatorjs.org

Also, this is the GitHub page for EmulatorJS:
https://github.com/EmulatorJS/EmulatorJS

EmuWeb supports the same consoles & systems that EmulatorJS supports (at the
time of this writing); thus, there are some consoles & systems that EmuWeb might
not support. In the future, EmuWeb may be extended to support emulation of other
systems by using other JavaScript emulation engines, if available.

To see an example of EmuWeb, you can load either of the following URLs from my
BBS (Digital Distortion):
http://www.digitaldistortionbbs.com/emulation/EmuSoft.xjs
http://digdist.synchro.net/emulation/EmuSoft.xjs

No ROMs are included in the archive. You will need to find ROMs and copy the
ones you want to host in the applicable subdirectories.

EmuWeb allows you as the sysop/maintainer of your Synchronet web site to simply
copy ROMs into the appropriate subdirectories, and EmUWeb will see them and
dynamically display systems and their ROMs/games. If any supported console or
system doesn't have any ROMs in its associated directory, it won't be displayed
on the main EmuWeb page.

Note that file naming for ROMs should simply include the name of the game.
Extra parts of the filenames (such as country codes like (U), (USA), (J), etc.,
and other pieces such as [!] etc.) should be removed - this particularly helps
with metadata matching.

The main page is EmuSoft.xjs. When that page is loaded, a set of systems (with
ROMs detected) is displayed, with images of each system. When a user clicks on
a system, it will open GameList.xjs in a new browser tab with an image of the
system & a list of its ROMs/games. A user can then click on one of the games,
which will open a pop-up with an EmulatoRJS instance to run the game. The pop-up
will have an X in the upper-right, which the user can click on to stop playing
the game and close the pop-up.

Also, EmuWeb can optionally retrieve game metadata online from IGDB (Internet
Game Database) or Rawg. If metadata is enabled, then when displaying a list of
games for a system, cover art for the games will be shown if available; also,
when a user hovers their mouse over a game name, a summary of the game will be
displayed in a pop-up.

EmuWeb also caches the information it finds about the ROMs (including metadata,
if enabled) to make future loads faster. The cached ROM data is stored in
sbbs/ctrl/dd_emu_web_cfg.json .


3. Installation & Setup
=======================
To install EmuWeb on your Synchronet BBS, perform the following steps:

- 1. From the extracted archive, copy dd_emu_web_common.js from mods/load
to your sbbs/mods/load directory.

- 2. From the extracted archive, copy the emulation directory to your web
root directory. You can find your web root directory by checking your
configuration in sbbs.ini (which is in sbbs/ctrl): In the [Web] section, look
for the RootDirectory setting. If you're using echicken's webv4, for instance,
this setting may be set to ../webv4/root; thus, your web root would be
sbbs/webv4/root. After copying, you should (in this example) have a
sbbs/webv4/root/emulation directory, with the contents of emulation from the
archive.

- 3. In a web browser, go to the EmulatorJS GitHub page and download a copy of
EmulatorJS:
https://github.com/EmulatorJS/EmulatorJS

You can download EmulatorJS from the GitHub page by clicking the green "Code"
button and choosing "Download ZIP". Unzip that, and then copy the contents of
their data directory to your emulation/data directory in your web root.

- 4. Copy the following section into your modopts.ini (in sbbs/ctrl):
[dd_emu_web]
	open_item_in_new_tab = false
; Web-pathed CSS filenames that you want to include for your web site,
; for desktop and mobile. If the mobile list is empty, then the ones from
; the desktop list will be used, if there are any specified.
; Each can be a single filename or a comma-separated list of filenames.
	additional_desktop_css_filenames = 
	additional_mobile_css_filenames = 
; Fully-pathed executables for crc32, md5sum, and sha1sum
	crc32_path = /usr/bin/crc32
	md5sum_path = /usr/bin/md5sum
	sha1sum_path = /usr/bin/sha1sum
; Whether or not to enable retrieving game metadata from online sources (true/false)
	get_metadata_online = false
; Maximum Levenshtein distance for game name matching (at least with RAWG)
	game_metadata_name_max_levenshtein_distance = 15
; Which game metadata service to use (igdb or rawg)
	game_metadata_service = rawg
; Client ID and access token for use with IGDB (Internet Game Database)
	igdb_client_id = 
	igdb_access_token = 
; API key for use with RAWG game database
	rawg_api_key = 

- 5. Find some ROMs you'd like to host and copy them to the appropriate ROM
directories under emulation/ROMs in your web root. 
Some of the ROM directories may need some explanation for which systems they're
for:
- C64: Commodore 64
- C128: Commodore 128
- GB: Nintendo GameBoy
- GBA: Nintendo GameBoy Advance
- GBC: Nintendo GameBoy Color
- N64: Nintendo 64
- NDS: Nintendo DS
- SegaGG: Sega Game Gear
- SegaMS: Sega Master System
- SegaGenesis: This is also known as Sega Mega Drive outside of North America
- TGX16: NEC TurboGrafX-16 (also known as the PC Engine outside of North America)

Note that file naming for ROMs should simply include the name of the game.
Extra parts of the filenames (such as country codes like (U), (USA), (J), etc.,
and other pieces such as [!] etc.) should be removed - this particularly helps
with metadata matching.

If EmuWeb is not finding any ROMs, one reason might be that your web root
directory is configurd incorrectly. See the section "Synchronet's web root
directory setting" for more information.

- 6. Optional: If you want to enable metadata, follow the instructions in
section 4 of this document (Metadata). Note that downloading metadata can take
a very long time (especially if you have many ROMs).


After completing these steps, load /emulation/EmuSoft.xjs in your web browser.
The first time it loads, it will display status for analyzing the ROM
directories, such as this:

Scanning games...
Arcade (105 ROMs)... 100.00%
Atari 2600 (772 ROMs)... 100.00%
GameBoy (2 ROMs)... 100.00%
GameBoy Advance (10 ROMs)... 100.00%
GameBoy Color (29 ROMs)... 100.00%
Nintendo 64 (9 ROMs)... 100.00%
Nintendo DS (3 ROMs)... 23.47%

..and so on, for the rest of the directories with ROMs.

Once that is done, it will display the set of systems to display, and subsequent
loads will be quick due to caching.


If you want to have it clear the cache and re-analyze all the ROMs, you can
pass clearCache=true on the query string for the EmuSoft.xjs URL. For instance:
http://<your_BBS_domain>/emulation/EmuSoft.xjs?clearCache=true

Replace <your_BBS_domain> with your BBS's domain. Also, if you have https
enabled, you may choose to use https instead of http.

For an individual console/system, you can have it refresh its metadata (if
enabled) by passing metaRefresh=true for GameList.xjs. You can first load a
console/system's page in your web browser and then add &metaRefresh=true
and refresh. For instance, for NES:
http://<your_BBS_domain>/emulation/GameList.xjs?core=nes&sysName=Nintendo%20Entertainment%20System&gameSystem=NES&igdb_system_id=18&rawg_system_id=49&imgFilenames=NES.webp&metaRefresh=true
Again, replace <your_BBS_domain> with your BBS's domain. Also, if you have https
enabled, you may choose to use https instead of http.


4. Configuration file options
=============================
This is an explanation of the configuration options in the [dd_emu_web] section
for modopts.ini:

Option                            Description
------                            -----------
open_item_in_new_tab              Whether or not to open items (games) in a new
                                  tab. If false, games will be opened in a pop-
                                  up dialog.

additional_desktop_css_filenames  Optional: A comma-separated list of additional
                                  CSS filesto use for the web pages in a desktop
                                  web browser. The CSS filenames should be
                                  pathedrelative to your web root directory.
                                  This can be a single filename.

additional_mobile_css_filenames   Optional: A comma-separated list of additional
                                  CSS filesto use for the web pages in a desktop
                                  web browser. The CSS filenames should be
                                  pathedrelative to your web root directory.
                                  This can be a single filename.
								  
crc32_path                        A fully-pathed executable for a crc32 program
                                  to calculate crc32 values for files (used for
                                  ROM file metadata matching. The included value
                                  is /usr/bin/crc32, which is valid for some
                                  Linux distributions. If you're running your
                                  BBS on Linux, you should ensure that you have
                                  crc32 installed, double-check its path, and
                                  update this setting if necessary. If you're
                                  running your BBS on Windows, you'll need to
                                  download a crc32 command-line program and
                                  change this setting; see the section "Windows:
                                  Downloading 3rd-party crc32, sha1sum, and
                                  md5sum utilities" for some suggested links to
                                  download these utilities.

md5sum_path                       A fully-pathed executable for a md5sum program
                                  to calculate md5 values for files (used for
                                  ROM file metadata matching. The included value
                                  is /usr/bin/md5sum, which is valid for some
                                  Linux distributions. If you're running your
                                  BBS on Linux, you should ensure that you have
                                  md5sum installed, double-check its path, and
                                  update this setting if necessary. If you're
                                  running your BBS on Windows, you'll need to
                                  download a md5sum command-line program and
                                  change this setting; see the section "Windows:
                                  Downloading 3rd-party crc32, sha1sum, and
                                  md5sum utilities" for some suggested links to
                                  download these utilities.

sha1sum_path                      A fully-pathed executable for a sha1sum
                                  program to calculate sha1sum values for files
                                  (used for ROM file metadata matching. The
                                  included value is /usr/bin/sha1sum, which is
                                  valid for some Linux distributions. If you're
                                  running your BBS on Linux, you should ensure
                                  that you have sha1sum installed, double-check
                                  its path, and update this setting if
                                  necessary. If you're running your BBS on
                                  Windows, you'll need to download a sha1sum
                                  command-line program and change this setting;
                                  see the section "Windows: Downloading 3rd-
                                  party crc32, sha1sum, and md5sum utilities"
                                  for some suggested links to download these
                                  utilities.

get_metadata_online               Whether or not to enable retrieving game
                                  metadata from online sources (true/false)


game_metadata_name_max_levenshtein_distance
                                  Maximum Levenshtein distance for game name
                                  matching (currently used for RAWG).
                                  Levenshtein distance is basically the
                                  difference in number of letters/characters
                                  between two words. For more information, see
                                  https://en.wikipedia.org/wiki/Levenshtein_distance


game_metadata_service             Which game metadata service to use (igdb or
                                  rawg)

igdb_client_id                    Client ID for use with Internet Game Database

igdb_access_token                 Access token for use with Internet Game
                                  Database)

rawg_api_key                      API key for use with RAWG game database


5. Synchronet's web root directory setting
==========================================
EmuWeb is able to find its files (such as ROMs, images, etc.) based on the web
root setting in Synchronet's configuration. EmuWeb reads the web root directory
setting from ctrl/sbbs.ini. Note that the .ini configuration files are available
in Synchronet 3.20 and above (earlier versions used the binary .cnf format). The
web root directory is specified in the [Web] section of sbbs.ini with the
RootDirectory setting. If you're using ecwebv4, this setting will likely be
../webv4/root, unless you've changed it to something different. The web root
setting is also configurable in SCFG in Servers > Web Server > Content Root
Directory.

If EmuWeb is unable to read the RootDirectory setting from the [Web] section in
sbbs.ini, then EmuWeb will try the [web] section in modopts.ini (which is where
the ecwebv4 settings are stored) - It will try the web_directory setting (and
then append "/root/"); if that fails, it will try to read web_root if that
exists (it seems older versions of ecweb may have had web_root).

If EmuWeb is not finding any ROMs, one reason might be that your web root
directory is configurd incorrectly.


6. Metadata
===========
If you want to enable metadata (to include cover art and descriptions), you can
sign up for your own API account with IGDB and/or Rawg, and you will need to
copy & paste your credentials for those into the appropriate settings in the
dd_emu_web section of your modopts.ini.

You can create an IGDB API account here (in a web browser):
https://api-docs.igdb.com/#getting-started

Follow their steps under "Account Creation". They first require you to have a
Twitch account (they have a link to Twitch to do so). Once you've created your
IGDB account, go to your IGDB user profile and copy & paste your client ID and
access token and paste them in the igdb_client_id and igdb_access_token settings
in your dd_emu_web section in modopts.ini.

To create an account with Rawg, open the following page in a web browser and
then click the "Get API Key" button:
https://rawg.io/apidocs

Click the link to sign up for an account. Once you've done that, go into your
Rawg user profile & copy & paste your Rawg API key to the rawg_api_key setting
in your dd_emu_web section in modopts.ini.

Once you've created one or both of those accounts, you can set the
get_metadata_online setting to true in your dd_emu_web section in modopts.ini.
Also, for the game_metadata_service setting, you can specify either rawg or igdb .

Also note that if you want to download metadata, a few important settings (in
the dd_emu_web section of modopts.ini) are crc32_path, md5sum_path, and
sha1sum_path. These are the paths to the executable files for crc32, md5sum, and
sha1sum. The included values are valid for some Linux systems but may still need
to be changed for some systems. For Windows, you will need to download the
Wnidows versions if you haven't already, and then provide the full paths &
filenames for these executables on your system.


7. Windows: Downloading 3rd-party crc32, sha1sum, and md5sum utilities
======================================================================
If you're running your BBS in Windows, you will need to download some 3rd-party
command-line crc32, sha1sum, and md5sum utility programs that work like the *nix
versions, and then configure the crc32_path, md5sum_path, and sha1sum_path
options in the [dd_emu_web] section of modopts.ini to specify their fully-pathed
filenames. Note that as of this writing, I haven't tested the use of any such
Windows tools with EmuWeb.

For Windows, this page has download links for command-line crc32 and md5
utilities:
https://esrg.sourceforge.net/utils_win_up/md5sum/

This GitHub page has source code for a Windows crc32 utility, but it would need
to be compiled/built:
https://github.com/vurdalakov/crc32

While it's possible to use certutil in Windows to get a sha1, EmuWeb doesn't
support that tool due to its command-line syntax. A 3rd-party sha1 command-line
program will need to be downloaded.

There is a freeware command-line sha1 tool available for download here:
https://di-mgt.com.au/generate-file-checksums.html

Download their digsum zip file (currently, digsum-1.0.1.zip) and unzip it. Their
sha1sum.exe is a command-line tool that can provide a sha1.


8. Notes
========
These are the subdirectories in the emulation directory and what they're for:
- data: The EmulatorJS data files need to be copied here
- database: This directory contains database files from No-Intro; these
  currently aren't used, but these may be used in the future.
- img: This directory contains images of various consoles/systems.
- ROMs: This containst the various subdirectories for ROMs for various consoles
  and systems.
