xungeons/README.md

Small Dungeon Crawler Specification

 _____   ____     ____   _____
/ ___|  |  _ \   / ___| / ___|  Small
\___ \  | | | | | |     \___ \  Dungeon
 ___) | | |_| | | |___   ___) | Crawler
|____/  |____/   \____| |____/  Specification

Source Code

General:

• This specification can be implemented in any programming language and in any formatting style.
• True aim is that it should be minimal in terms of source lines of code, and resource usage when possible.
• All memory leaks should be cleaned, which can be checked with Valgrind, compiler warnings aren't taken in account.
• Some APIs, drivers and libraries like SDL2, Raylib, OpenGL and Vulkan leak memory, those leaks are forgiven.
• Also, cleaning up all compiler and/or linter warnings is a benefit, but is not required at all.

Scoring:

• As this was intended as a challenge for various programming languages and programmers, scoring rules are:

+2 points per weapon, armour, jewelry, enemy, attribute, skill, class or spell definition.
+1 point per full line of code (in C, this means that blank lines or lines with characters '{', '}', '};', '},' are ignored).
-1 point per compiler warning, on maximum warning options (in C, that would be -Weverything or -Wall -Wextra).
-2 points per memory leak of 10 bytes (again, libraries and drivers aren't accounted in this case, they can leak).

• Then, final score is the total number of points divided by count of lines of code.

Gameplay

General:

• Note that further explanations for gameplay elements are given separately, in text below for consistency.
• Game screen layout consists of 2 panels, on the left is world state preview, on the right is player state preview.
• World state is updated on every action (key pressed), unless some menu is active, which includes animations and bots too.
• Default keyboard action mapping must be consistent across games that follow this specification, but bindings are allowed.
• Important gameplay elements must be implemented, and the amount of them is up to developer to decide.

Default keyboard action mapping:

Use        - KP0 - O
Inventory  - KP- - I
Wait       - KP5 - .
Up         - KP8 - K
Down       - KP2 - J
Left       - KP4 - H
Right      - KP6 - L
Up+Left    - KP7 - Y
Up+Right   - KP9 - U
Down+Left  - KP1 - B
Down+Right - KP3 - N

Examples:

• Game following this specification can be implemented in terminal or graphical window, as developer decides.
• It's not important if game has 3 or 300 types of weapons or armours, it's important that it has them.
• Lastly, it's important to have most minimal implementation in terms of source lines of code, for any language.

Elements:

• Attributes influence health, mana, stamina and experience points of all creatures (party members and bots).
• Skills are passive abilities influencing damage, condition, proficiency and other item usage modifiers.
• Spells are active abilities (activated when casted) that apply certain effects on the world state.
• Potions, manuals and scrolls are items that temporarily increase or decrease any previously defined element.
• Weapons are equipment that must have attack category, damage, condition, value.
• Armours are equipment that must have defence category, resistance, condition and value.
• Jewelry is type of equipment that can be enchanted and give some effect to party member.
• Coins are collectively gathered and can be used for trading, buying and selling items and other equipment.

Player

General:

• Player controls party of 6 characters (like in Wizardry), as one group in tactical turn-based combat.
• Each party member has health, mana, stamina and experience points, attributes, skills, spells, equipment and inventory.
• Collectively, party has coins (currency), equipment and inventory, which can be shared and redistributed.
• Movement is done with Keypad and Vim-like-keys, respectively KP1...KP9 and H, J, K, L, Y, U, B, N and fullstop.
• All party members are randomly generated, they have randomized attributes, skills, spells and equipment.

Enemies

General:

• When an enemy is in view range of player, they'll start following until they enter the battle state.
• Enemies always leave random amount of coins, and randomly some item like potion, scroll or manual.
• Attack decisions are made by attacking ranged and magical party members (archers and wizards) first, then fighers.

Dungeons

General:

• Every dungeon level is 2D matrix (tilemap or gridmap) of random width and height in arbituary limitation.
• Procedural generation is up to developer to implement, but level layouts and elements must always be randomly generated.
• Maximum width and height limitation is undefined (developer choice), minimum width and height must be respectively 80 and 24.
• Elements of dungeon are walls (clip), floors (noclip), decorations (clip/noclip) and special elements (defined below).
• Special elements of dungeons execute game state changing arbituary function when 'use' command is given.
• Difficulty is tied to number of levels passed, it increments with each level, and generates rarer dungeon elements.
• Player can go down to next level, but never return to previous level, no stair-hopping allowed.

Terminal extension:

• Basic VT100 escape codes should be used to output buffers in colours, offset the cursor and change screen size.
• Visually distinct colours and styles should be used to express different game elements (defined below).
• Terminal should be updated in real-time and include size changes, using curses-like approach to print at terminal size offset.

@           CYAN   BLINK   - Player (blinking for easier recognition)
#           GREY   REVERSE - Wall (biome can be expressed with colour)
.           GREY   REVERSE - Floor (biome can be expressed with colour)
>           PINK   BOLD    - Stairs (go to next level)
}           PINK   BOLD    - Portal (go to random noclip tile)
a...z|A...Z RED    ITALIC  - Enemies (weaker lowercase, stronger uppercase)
$           WHITE  BOLD    - Coins (random number)
)           YELLOW NORMAL  - Shooting weapons (bow, crossbow, sling...)
|           YELLOW BOLD    - Piercing weapons (spear, halberd, lance...)
!           YELLOW BOLD    - Slashing weapons (sword, greatsword, dagger...)
?           YELLOW BOLD    - Swinging weapons (axe, mace, flail...)
/           YELLOW ITALIC  - Magical weapons (staff, wand...)
-           GREEN  NORMAL  - General jewelry (ring, amulet, earing...)
]           GREEN  BOLD    - General armours (complete set)
=           BLUE   NORMAL  - General potions (affect attributes)
%           BLUE   BOLD    - General manuals (affect skills)
;           BLUE   ITALIC  - General scrolls (affect spells)

Graphical extension:

• Every tile (2D sprite) should be of same dimensions for pixel art, to form a grid, loaded as a spritesheet or individual sprites.
• Optionally, sprite-overdraw can be used to draw on top of player sprite, for example armours and weapon sprites.
• Unlike with terminal extension rules, there are no visual rules here, it's up to common sense of the developer to make them.

Battles

• Each party member gets the turn to do one combat action (defined below), then one of the enemies does the same.
• Battle is over when all party members or enemies are dead, and battle menu is hidden until next battle.
• Combat actions are attack, block, shoot (ranged), evoke (magical), cast (spell), quaff (potion), read (scroll) and wait (skip).
• Attack, block and shoot use stamina points, which can be recovered on wait or when party is resting after the battle.
• Evoke and cast use mana points, which can be recovered slowly but automatically after the battle.