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 from STDIN 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 or 1. Uses the JSF random number generator (see src/jsf.c).

display_cellobjs

Returns a string usually shown in the status bar consisting of the VEGGIE (item, if any) and MINERAL (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) has WHERE, MINERAL, VEGGIE, and ANIMAL 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 and max - 1. Uses the JSF random number generator (see src/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 (see src/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 be roll(3,6). Uses the JSF random number generator (see src/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:

http://burtleburtle.net/bob/rand/smallprng.html