Copyright 2010-2021 Adam Nielsen <firstname.lastname@example.org>
libraries to provide a single unified interface to supported games. With this
library, rather than having to know which archive files to open and what each
file is for, all that is abstracted away and instead a list of items is
provided. Each item can be "opened", which will return an instance of whatever
the file happens to be - a
Map instance from gamemaps.js if it's a game
level, or a
Music instance from gamemusic.js if it's a song, and so on.
Installation as an end-user
Although not the intended use (due to limited functionality), you can install
the library as an end-user and use the command-line
gameinfo utility to work
with games directly. To install it globally on your system:
npm install -g @camoto/gameinfo
The library currently supports these games:
- Cosmo's Cosmic Adventure (episode 1) [incomplete]
- Dangerous Dave [incomplete]
Command line interface
gameinfo utility can be used to access some of the library's
functionality. Commands are specified one after the other as parameters. Use
--help option to get a list of all the available commands. Some quick
# List available items in a game, autodetected from the files found in the # given folder. gameinfo open /dos/games/cosmo list # Rename an element and save changes. This changes the filename inside # COSMO1.VOL as well as patching COSMO1.EXE to use the new name. gameinfo open /dos/games/cosmo select music.19 rename newfile.mni save # Extract the title screen and save as a PNG image. gameinfo open /dos/games/cosmo select splash.title export -t img-png title.png # Load the PNG image again and use it to replace the title screen. gameinfo open /dos/games/cosmo select splash.title import title.png save
To get a list of supported games, run:
Installation as a dependency
If you wish to make use of the library in your own project (the intended purpose!), install it in the usual way:
npm install @camoto/gameinfo
cli/index.js for example use. The quick start is:
import GameInfo from '@camoto/gameinfo'; import Filesystem from '@camoto/gameinfo/interface/filesystem.js'; let fs = new Filesystem('/dos/games/cosmo'); const handler = GameInfo.getHandler('game-cosmo'); const game = new handler(fs); const warnings = game.open(); console.log('Warnings:', warnings);
Installation as a contributor
If you would like to help add more games to the library, great! Clone the repo, and to get started:
Run the tests to make sure everything worked:
Most of the tests require original files from the games, which aren't part of the git repo. So to fully run the tests (and to add support for new games) you'll need to copy the game files into the test folder:
Find out the identifier for the game in question, e.g.
game-ddaveis the identifier for Dangerous Dave.
Make a folder with this name inside the
testfolder, so in this case the command would be
Copy the game files into this new folder. Only the files read and written by the format handler need to be included, but extra files (such as the game's documentation files) won't hurt.
Run the tests again and confirm they are no longer showing as "skipped". You can run only the tests for this game with a command like
npm test -- -g game-ddave.
Now you're ready to go! To add a new game:
First make sure the file formats you need have been implemented in the other support libraries, e.g. all the archive formats are supported by gamearchive.js, the levels by gamemaps.js, the images by gamegraphics.js, and so on.
Create a new file in the
games/folder for your game. Copying an existing file that covers a similar game will help considerably.
games/index.jsand add an
importstatement for your new file.
During development you can test your code like this:
# Open a sample game and list the files, with debug messages on. $ DEBUG='game*' ./bin/gameinfo.js open /path/to/game list # Run the unit tests just for this game, using game-ddave as an example. $ DEBUG='gameinfo:*' npm test -- -g game-ddave # Run all the unit tests to ensure code passes the lint checks. $ DEBUG='gameinfo:*' npm test
Only very basic checks are performed with the standard tests. You should create an extra test file that actually performs some modifications, to ensure everything is functioning correctly.
This is done by creating an extra
.js file in the
test/ folder. Copy one
of the existing files such as
test/game-ddave.js to use as an example. The
new file will be picked up automatically when the tests are run.
Once your code is at the point where you've gone as far as you can go with the CLI and unit tests, you will probably want to test it with the web version of Camoto, so you can view images, maps, etc.
To do this, clone the studiojs repo and follow the instructions to get it running locally. Then replace the gameinfojs dependency with your local version:
cd studiojs npm remove @camoto/gameinfo npm install ../gameinfojs # Use the path to your local copy
This will then make your local web UI use your development gameinfojs code, so you can test out your changes before sending in a PR.
You can do a similar thing in gameinfo.js, removing one of the other dependencies (say @camoto/gamemap) and replacing it with a local instance. In this example, you would be able to change level reading/writing code in gamemap.js and test it immediately through the web UI when opening a game level. Depending on your caching/file watching settings, you may need to restart the local web UI server before it picks up your changes.