NAME
Game::Xomb - a game featuring @ versus the Xarci Bedo
SYNOPSIS
Xomb is a terminal-based roguelike. Assuming that the development tools (C99 support is required), perl(1), App::cpanminus, and optionally local::lib are installed and setup in a suitable terminal install and run the game via:
cpanm Game::Xomb
xomb
Use the ?
key in game to show the help text. The xomb documentation details other useful game information; it should be available once the module is installed via:
perldoc xomb
The remainder of this documentation concerns internal details likely only of interest to someone who wants to modify the source code.
DESCRIPTION
The game is data oriented in design; adding a new floor tile would require a new SPECIES
constant, suitable entries in %Thingy
, %Descript
, and @Level_Features
, and then any additional code for passive effects or whatever. Various routines may need adjustment for a new floor type as there is not a good component system to indicate whether a floor tile is solid, dangerous, etc. A new monster would require similar additions, and would need a custom update_* function for when that critter has an action to make.
Only the player can move, so much of the code assumes that. New player actions would need to be added to %Key_Commands
and suitable code added to carry out the new action.
All entropy comes from the JSF random number generator (see src/jsf.c
). The perl built-in rand
function MUST NOT be used; instead use irand, roll, or one of the other utility functions that call into the JSF code.
There are tests for some of the code, see the t
directory in the module's distribution.
FUNCTIONS
- abort_run
-
Called by the movement code to determine whether the run should be aborted, e.g. before the player steps to a pool of acid.
$Sticky
indicates whether a run is in progress, and runs are caused by the move_player_runner or move_player_snooze functions, see%Key_Commands
. - apply_damage
-
Removes hitpoints from the given animate, with complications to report the damage and to mark the game as over (for the player) or otherwise the monster as dead. Calls over to
%Damage_From
table entries which return the damage as appropriate for the arguments. - at at_col at_row
-
These routines move the cursor around the terminal. at takes arguments in col,row (x,y) form.
- apply_passives
-
Floor tiles can have passive effects that can vary depending on the duration the player is within the cell, or could be a message to the player. See passive_burn, passive_msg_maker.
- await_quit
-
Waits for the player to quit usually from a submenu.
$RKFN
holds the function that read keys; these could either come fromSTDIN
or from a save game file. - bad_terminal
-
Indicates whether a terminal exists and is of suitable dimensions.
- bail_out
-
Called when something goes horribly wrong, usually on fatal signal or internal error.
- between
-
Like
clamp
from the Common LISP Alexandria library. - bypair callback list ...
-
Calls the callback function with pairs of items from the given list of items.
- coinflip
-
Returns
0
or1
. Uses the JSF random number generator (seesrc/jsf.c
). - display_cellobjs
-
Returns a string usually shown in the status bar consisting of the
VEGGIE
(item, if any) andMINERAL
(floor tile) of the cell the player is in. - display_hitpoints
-
Returns a string that prints the player's shield points in the status bar.
- display_shieldup
-
Returns a string that prints whether and if so what
VEGGIE
is being used to regenerate the shield. - distance
-
Pythagorean distance between two cells, with rounding. Will differ in some cases from the Chebyshev distance that the linecb and walkcb line functions use for an iterations count.
- does_hit
-
Whether or not the given weapon hits at the given distance, and what the cost of that move was. The cost will be higher if the target is out of range so that the animate will not wake up until the player can be in range.
- extract
-
Removes a random element from the given array reference and returns it. Uses the JSF random number generator (see
src/jsf.c
).Note that the original order of the array reference will not be preserved. If that order is important, do not use this call. Order preserving extraction can be done with:
... = splice @array, irand(scalar @array), 1;
- fisher_yates_shuffle
-
Shuffles an array reference in place. Uses the JSF random number generator (see
src/jsf.c
). - game_loop
-
Entry point to the game, see
bin/xomb
for how this gets called and what needs to be setup before that. Loops using a simple integer based energy system over active animates and calls the update function for each on that gets a go, plus some complications to change the level, etc. - game_over
-
Called when the game needs to exit for various reasons mostly unrelated to gameplay (terminal size too small, fatal signal).
- generate_map
-
Generates a level map around where the player is. Various knobs can be found in
@Level_Features
. - getkey
-
Reads a key from the terminal until one in the hash of valid choices is entered. See also
$RKFN
. - has_amulet
-
Whether the player is carrying (or has equiped) the Amulet.
- has_lost
-
Exits game with death screen and score.
- has_won
-
Exits game with win screen and score. Should be the only
0
exit status of the game. - help_screen
-
In game information on keyboard command available
- init_jsf
-
Sets the seed for the JSF random number generator (see
src/jsf.c
). - init_map
-
Initial setup of the
@LMap
. This is in row,col form though points use the col,row form. Each cell (LMC
) hasWHERE
,MINERAL
,VEGGIE
, andANIMAL
slots that contain a col,row point for the cell, the floor tile, item (if any), and animate (if any). - irand max
-
Integer random value between
0
andmax - 1
. Uses the JSF random number generator (seesrc/jsf.c
). - linecb callback x0 y0 x1 y1
-
Bresenham line function with some features to keep it from going off of the map and to skip the first point and to abort should the callback return
-1
. - log_dim
-
Used to bold -> normal -> faint cycle log the most recent message (shown at the top of the screen) depending on the age of the message.
- log_message
-
Adds a message to the log and displays it at the top of the screen.
- loot_value
-
Returns the value of the loot the player is carrying.
- make_amulet
-
Creates the amulet and returns it.
- make_gem
-
Creates a gem and returns it.
- make_monster
-
Creates a monster and returns it. Suitable parameters must be supplied.
- make_player
-
Creates the player, places them into the
HERO
slot of the@Animates
array, and returns the col,row starting position of the player. generate_map builds the level map around this position. - manage_inventory
-
A far too complicated routine to inspect, drop, or equip items in the inventory list.
- move_animate
-
Moves the player around the level map, with various game related complications. See
%Key_Commands
and move_player_maker. - move_drop
-
Drops an item from the inventory.
- move_equip
-
Equips an item from the inventory.
- move_examine
-
Lets the player move the cursor around the level map to inspect various features.
- move_gate_down
-
For when the player climbs down the "stairs".
- move_gate_up
-
For when the player tries to climb up the "stairs".
- move_nop
-
For when the player rests for a turn.
- move_pickup
-
Picks an item (if any) up off of the level map.
- move_player_maker
-
Creates a function suitable for moving the player in a particular direction. See
%Key_Commands
. - move_player_runner
-
Creates a function suitable for running the player in a particular direction.
- move_player_snooze
-
Creates a function suitable for resting with over multiple turns.
- move_quit
-
Prompts whether they want to quit the game.
- move_remove
-
Unequips an item (if any).
- nope_regarding
-
Query the player whether they want to carry out some dangerous move.
- onein max
-
Returns true if the RNG rolls
0
within max. Uses the JSF random number generator (seesrc/jsf.c
). - passive_burn
-
Apply acid damage because the player is in a pool of acid.
- passive_msg_maker
-
Returns a subroutine that issues a message when a cell is entered into. The cell should probably be made unique with reify first as otherwise all floor tiles of that type will share the same update routine.
- pathable col row points ...
-
Ensures that a path exists between the given coordinates and the given list of points; used by generate_map to ensure that the player can reach all the gates and gems.
- pick
-
Picks a random item from the given array reference. Uses the JSF random number generator (see
src/jsf.c
). - pkc_clear
-
Clears the PKC error code from the status bar.
- pkc_log_code
-
Prints a PKC error code in the status bar.
- place_floortype
-
Used by generate_map to place floor tiles somewhat randomly (brown noise) around the level map, as controlled by
@Level_Features
counts. - place_monster
-
Creates and places a monster onto the level map, and that the monster has not been placed above a hole or in acid.
- plasma_annihilator
-
Displays and applies splash damage from Fungi attacks.
- raycast_fov
-
Calculates the FOV for the player and updates various related variables such as what monsters are visible.
- reduce
-
Reduces a map cell floor tile to
RUBBLE
. Some monsters can destroy walls. - refresh_board
-
Redraw the level map, status bar, and previous message if any.
- reify
-
Marks a particular level map item (
MINERAL
, typically) as unique, usually so that a passive_msg_maker can be applied to it. - relocate
-
Handles moving the player from one level map cell to another.
- replay
-
Replays commands from a save game file. See also
$RKFN
. - report_position
-
Logs a message showing where the player is on the level map.
- report_version
-
Logs a message with the game version, seed, and current turn number.
- restore_term
-
Gets the terminal out of raw mode and more back to normal.
- roll times sides
-
Dice rolling, so
3d6
would beroll(3,6)
. Uses the JSF random number generator (seesrc/jsf.c
). - rubble_delay
-
Slow the player down when they move in (or into, or out of) rubble.
- sb_update_energy
-
Update the energy cost of the last move.
- score
-
Returns a string with the game score in it.
- show_messages
-
Show all the recent messages in the message log.
- show_status_bar
-
Prints the status bar at the bottom of the screen.
- show_top_message
-
Prints the most recent log message at the top of the screen.
- update_fungi
-
UPDATE
function for fungi. - update_gameover
-
Custom
UPDATE
function for when the player is dead. - update_ghast
-
UPDATE
function for ghast. - update_mimic
-
UPDATE
function for mimics. - update_player
-
UPDATE
function for the player. Failed moves (zero-cost things) are looped over until a move that costs energy is made. Input comes from the$RKFN
which is usually a function that reads from standard input. - update_stalker
-
UPDATE
function for stalkers. - update_troll
-
UPDATE
function for trolls. - use_item
-
Uses an item, possibly swapping it with some existing item.
- veggie_name
-
Returns a string with the name and value of a vegetable (a gem, or the amulet).
- walkcb
-
Like linecb but continues until the edge of the level map or until the callback function returns
-1
. - with_adjacent col row callback
-
Runs the callback function for each cell adjacent to the given coordinates that is within the level map.
BUGS
HP 100
You plunge into the hole.
HP -140314714594444
'tis but a flesh wound.
https://thrig.me/src/Game-Xomb.git
SEE ALSO
Game::PlatformsOfPeril from which this code evolved.
7DRL 2020 - https://itch.io/jam/7drl-challenge-2020
Vektor - Terminal Redux
AUTHOR
Jeremy Mates
COPYRIGHT AND LICENSE
Copyright (C) 2020 by Jeremy Mates
This program is distributed under the (Revised) BSD License: http://www.opensource.org/licenses/BSD-3-Clause
The src
directory code appears to be under a "I wrote this PRNG. I place it in the public domain." license: