Tools for editing AGOS games (e.g., Simon the Sorcerer by AdventureSoft).

1. Introduction
2. Features
3. Supported Games
4. Installation
5. Usage
   1. Interactive (Wizard) Mode
   2. Command-Line (Spell) Mode
6. Getting Help
7. Contributions
8. Open Items
9. Thanks
10. Development
11. License

MAGOS is a tool for exploring, modifying, and enhancing AGOS games. Whether you want to translate, mod, or learn how these games work, MAGOS makes it easy to access and edit game resources.

• Unpack and Repack GME Archives
• Decrypt and Edit Game Texts
• Extract and Modify Voice Files
• Decompile and Recompile Game Scripts

MAGOS supports the following AGOS games:

• Elvira: Mistress of the Dark (elvira1)
• Elvira II: The Jaws of Cerberus (elvira2)
• Waxworks
  • Retail version (waxworks)
  • Demo version (waxworks-demo)
• Simon the Sorcerer
  • Floppy version (simon1)
  • Demo version (simon1-demo)
  • Talkie versions (CD and 25th Anniversary) (simon1-talkie)
• Simon the Sorcerer II: The Lion, the Wizard and the Wardrobe
  • Floppy version (simon2)
  • Talkie versions (Demo, CD, and 25th Anniversary) (simon2-talkie)
• The Feeble Files (feeble)
• Simon the Sorcerer's Puzzle Pack
  • Swampy Adventures (swampy)
  • NoPatience (puzzle)
  • Jumble (jumble)
  • Demon in My Pocket (dimp)

1. Download the latest release for your OS from the Releases page.
2. Extract the downloaded archive to a folder of your choice.
3. Run the tool directly from the extracted folder.

The program is a single executable file and does not require any additional dependencies.

MAGOS can be used in two modes: Interactive (Wizard) Mode (recommended for most users) and Command-Line (Spell) Mode (interface for advanced users). Both modes allow you to extract and work with various game resources, including texts, scripts, voices, and archives.

Interactive (Wizard) Mode provides a simple, menu-driven interface that guides you through the process of working with game resources. It is the default mode when the tool is run without any arguments (or with only the game directory path).

1. Summon the Wizard: Run the tool without any arguments:

   magos

   Or specify the game directory:

   magos PATH/TO/GAME

2. Select a Directory: Use the directory selection option to choose the game directory. If needed, switch to a different directory to work on another game.

3. Game Selection: The tool will attempt to detect the game automatically based on the directory contents and select it. If detection fails, you can manually select the game from a list.

4. Configure Features: Features are dynamically available based on the selected game. Use the interactive controls to toggle features like extracting scripts, archives, and voices, or to configure output file names and encoding settings.

5. Extract Resources: Use the "Extract" button to extract resources such as texts, voices, or scripts. The resources will be saved in the working directory, i.e., the folder you started the program from.

6. Modify Extracted Files: Make any desired modifications to the extracted files using external tools or editors. MAGOS itself does not provide editing capabilities for the extracted files.

7. Rebuild the Game: After making changes to the extracted files, use the "Rebuild" button to inject your modifications back into the game. If the rebuild process encounters any errors, they will be displayed in the output panel.

8. Exit: When you're done, select "Exit" or press Ctrl+D to close the tool.

Wizard Mode automatically saves your settings in a magos.toml file in the selected directory. These settings are restored when you select the same directory again.

Command-Line (Spell) Mode is designed for advanced users who prefer working with command-line tools or need to automate tasks. It allows you to specify actions and options directly via command-line arguments, providing flexibility for various use cases.

By default, running magos PATH/TO/GAME launches the tool in Wizard Mode. To run it in Spell Mode, use the -n flag:

magos PATH/TO/GAME -n

The tool always extracts all game texts and saves them to a file in the working directory. By default, the file is named strings.txt. You can customize the name or perform additional actions using the options below.

1. Change Output File Name: Use the -o flag to specify a custom name for the extracted texts file:

   magos PATH/TO/GAME -n -o messages.txt

2. Specify the Game: If the game is not detected correctly, you can manually specify the game using the -g flag:

   magos PATH/TO/GAME -n -g simon1

   Refer to the Supported Games section for the list of game identifiers.

3. Extract GME Archive: To extract the contents of a GME archive into a directory, use the -e flag:

   magos PATH/TO/GAME -n -e ext

   This will create a directory named ext in the working directory containing the extracted files.

4. Decompile Game Scripts: Use the -s flag to decompile game scripts and objects:

   magos PATH/TO/GAME -n -s

   This will create two files in the working directory:

   • scripts.txt for the decompiled script
   • objects.txt for object information

   To specify a custom name for the scripts.txt file, add the desired name after the -s flag:

   magos PATH/TO/GAME -n -s decomp.txt

   Similarly, to specify a custom name for the object information file, use the -i flag:

   magos PATH/TO/GAME -n -s decomp.txt -i items.txt

5. Extract Voice Files: Use the -t flag to extract voice samples from the game's soundbank:

   magos PATH/TO/GAME -n -t SIMON.VOC

   This will create a directory named voices in the working directory containing the extracted sound files.

6. Decrypt Strings: Use the -c flag to decrypt game texts for a specific language:

   magos PATH/TO/GAME -n -c he

   Supported languages include:

   • he for Hebrew
   • de for German
   • es for Spanish
   • fr for French
   • it for Italian
   • pl for Polish
   • ru for Russian

   You can also convert the decrypted texts to UTF-8 encoding using the -u flag:

   magos PATH/TO/GAME -n -c he -u

7. Rebuild the Game: The same command used to extract resources can also be used to rebuild them by adding the -r flag. For example:

   If you have extracted resources with the following command:

   magos PATH/TO/GAME -c he -e ext -s -t SIMON.VOC

   You can rebuild the game with:

   magos PATH/TO/GAME -c he -e ext -s -t SIMON.VOC -r

If you have questions or encounter issues, you can:

• Check the issues section on GitHub.
• Look for community resources or discussions.

Contributions are welcome! Feel free to submit issues, fork the repository, and send pull requests.

The following are potential areas for future exploration and improvement:

• Document the script language: Provide detailed documentation on the commands and structure of the script language to assist with editing and recompiling game scripts.
• Extract and edit game graphics (VGA files): Add support for extracting and modifying graphical assets.

Special thanks to:

• AdventureSoft for making these games.
• ScummVM and ScummVM Tools for their invaluable work, which made this project possible.
• MojoTouch for the Anniversary Edition.
• Hebrew Adventure Group for inspiring this project.
• Alan Cox for releasing AberMUD as free software.

To develop or contribute to this project, you can clone the repository and set it up using Python >= 3.12 and Poetry (a tool for dependency management and packaging in Python).

1. Clone the Repository:

   git clone https://github.com/adventurebrew/magos.git

2. Navigate to the Project Directory:

   cd magos

3. Ensure you have Python >= 3.12 installed: You can check your Python version by running:

   python --version

4. Install Dependencies: Install the required dependencies using Poetry:

   poetry install

5. Activate Poetry Shell: Activate the Poetry virtual environment:

   poetry shell

Now you have the magos program available to execute from your shell, with the ability to modify the program locally.

This project is licensed under the GPL-3.0 License. See the LICENSE file for more details.

Disclaimer: This is a fan-made project and is not affiliated with or endorsed by the copyright holders of the original AGOS games. All trademarks are the property of their respective owners.