Usage

• gext is a text based adventure game written in rust and saved in json

in game commands

• look: print the description of the room
• go [room]: move to another room (checks if you have the key)
• take [item]: take an item
• takekey [key]: take a key
• search: search the room for items, keys, and doors
• save: save the game
• battles: print the battles you've fought
• inventory: print the items and keys you have
• use: use an item now, but for only half the effect

debug-only in game commands

• debug: print current player and map data

Installation

using cargo

Prerequisites

• you need to have cargo installed (which comes with rust)
• to do this, run the following command in your terminal:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• this downloads the latest rust installer, then pipes it to your shell to run it
• follow the instructions in the installer (if you don't know what to do, just press enter)
• after the installer is done, you need to restart your terminal (by closing it and opening a new one, or by running exec <your shell>), or by running the following command:

source $HOME/.cargo/env

• this adds the cargo command to your path

Installation

• to install gext, run the following command in your terminal:

cargo install gext

• this downloads the latest version of gext from crates.io, then compiles and installs it
• then, assuming the installation of rust modified your path, you can run the game with the following command:

gext [OPTIONS]

• if the installation of rust did not modify your path, you can run the game with the following command:

~/.cargo/bin/gext [OPTIONS]

• if you are not using *nix, replace ~/.cargo/bin/gext with the path to the gext binary (which should be in the bin directory of the cargo installation directory, on windows, this is usually C:\Users\<your username>\.cargo\bin\gext.exe)
• if you are using *nix, you can add the bin directory of the cargo installation directory to your path by running the following command:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

using the binary

• the game is built on linux, so it should work on all linux systems
• to install gext, download the latest release from the releases page
• ensure to pick the correct binary for your system
• if your system is not listed, you can build the game from source, as detailed above

Playing

• this page contains some tips and tricks for playing the game

player stats

• the player has 3 stats: health, attack, and defense
• health is the amount of damage the player can take before dying
• attack is the amount of damage the player can deal to an enemy
• defense is the amount of damage the player can block from an enemy

doors

• doors are used to move between rooms
• some doors are guarded by an enemy, where you need to defeat the enemy to pass
• other doors are locked, where you need to find a key to pass

items

• items are used to buff the player
• items can be found in rooms
• items can be taken with the take command
• they buff one or more of the player's stats

enemies

• enemies are found behind doors
• enemies have stats, just like an ordinary player (in the game files, they are just an instance of the Player struct)
• enemies can be fought when attempting to pass a door (but you need the key first)
• by using the search command, you can check if a door is guarded by an enemy, or if it is locked
• once you attempt to pass a door, you can't go back (if you die, all your stats are reset, but any items you used in the battle are not returned to you)

saving

• the game can be saved with the save command
• at the start of each game, you are asked if you want to load a save file
• if you choose to load a save file, you are asked for the name of the save file
• game files usually have the .save.json suffix

Options

command line arguments

--map or -m to specify a map file, usually suffixed with .map.json

• if not specified, defaults to hard-coded map, which can be found at src/main.rs

Modding

• gext is an inherently moddable game, as it is saved in json
• though it should be pretty obvious, the details of how to mod the game are documented here
• Map
• Player Data

Map

• to modify the map, you can customise the map save file
• this is usually suffixed with .map.json
• the map save file is a json file, with the following structure:

examples

• here are some example rooms, from the default save
• note that all rooms that they reference (ie "East Dungeon Cell" etc.) are not included in this snippet, and can be found at (default.map.json)[https://github.com/werdl/gext/blob/main/default.map.json]

{
    "East Dungeon": {
        "name": "East Dungeon",
        "description": "a dark dungeon",
        "doors": [
            {
                "name": "East Dungeon Cell",
                "description": "a dark dungeon cell",
                "locked": false,
                "key": {
                    "name": ""
                },
                "enemy": null,
                "associated_room_name": "Dungeon",
                "requirements": null
            }
        ],
        "items": [
            {
                "name": "stick",
                "description": "a stick",
                "health": 0,
                "attack": 1,
                "defense": 0
            }
        ],
        "keys": []
    }
}

• this one describes a simple room, that contains a stick, and a door to a dungeon cell

"Armory": {
        "name": "Armory",
        "description": "a room with a lot of weapons",
        "doors": [
            {
                "name": "Trophy Cupboard",
                "description": "a room with a lot of trophies",
                "locked": true,
                "key": {
                    "name": "trophy cupboard"
                },
                "enemy": {
                    "class": {
                        "name": "Default",
                        "description": "Looks like somebody didn't choose a class...",
                        "health": 100,
                        "attack": 10,
                        "defense": 10,
                        "starting_items": [],
                        "starting_keys": [],
                        "won_battle_attack_bonus": 5,
                        "won_battle_defense_bonus": 5,
                        "won_battle_health_bonus": 5
                    },
                    "name": "Trophy Keeper",
                    "map": {},
                    "items_held": [],
                    "keys_held": [],
                    "health": 100,
                    "attack": 20,
                    "defense": 10,
                    "battles": [],
                    "current_room": {
                        "name": "Empty Room",
                        "description": "a room with nothing in it",
                        "doors": [],
                        "items": [],
                        "keys": []
                    },
                    "game_name": ""
                },
                "associated_room_name": "Trophy Cupboard",
                "requirements": null
            }
        ],
        "items": [
            {
                "name": "shield",
                "description": "a shield",
                "health": 20,
                "attack": 0,
                "defense": 0
            },
            {
                "name": "axe",
                "description": "a sharp axe",
                "health": 0,
                "attack": 20,
                "defense": 0
            }
        ],
        "keys": [
            {
                "name": "trophy cupboard"
            },
            {
                "name": "pantry"
            }
        ]
    }

• this one describes a room with a shield, an axe, and a door to a trophy cupboard
• the trophy cupboard is locked, and contains an enemy
• the enemy is a Trophy Keeper, with 100 health, 20 attack, and 10 defense

Player Data

How to customise items held by user, user stats etc

• all player data is stored in the game save file, a serialized Player instance
• therefore, by editing it after saving and before loading, you can customise the player's stats, items, and keys

player stats

• the player has 3 stats: health, attack, and defense
• these are all integers
• to edit, change the health, attack, and defense fields in the Player struct (at top level of the json file)

items

• items are stored in the items_held field of the Player struct
• to add an item, add a new item to the items_held array
• to remove an item, remove the item from the items_held array

keys

• keys are stored in the keys_held field of the Player struct
• these can be added and removed in the same way as items

battles

• battles are stored in the battles field of the Player struct
• this is an array of Battle structs
• to add a battle, add a new battle to the battles array
• to remove a battle, remove the battle from the battles array

current room

• the current room is stored in the current_room field of the Player struct
• this is a Room struct

game name

• the game name is stored in the game_name field of the Player struct
• exactly why you would want to change this is beyond me, but you can, I guess

An Introduction to Rust for Java Developers