NCURSES Derby Horse Racing Game

Introduction

Welcome to the second release (v2.0) of NCURSES Derby Horse Racing, a terminal- based horse racing simulation for Linux. Watch horses (represented by ~/^\^) race on a straight horizontal track in your command shell! This release intro- duces SQLite3 database integration to store race results, player data, and statistics, alongside enhanced gameplay with fast and slow race modes, random payouts, and a menu-driven interface.

Features

• Gameplay: Bet on one of 10 horses to finish Win, Place, or Show, watch the race in real-time, and check results with payouts.
• Race Modes: Fast mode (~16–21 seconds, ideal for testing) and slow mode (~100–120 seconds, realistic pacing akin to the 2025 Kentucky Derby’s 122.31s).
• Data Storage: Stores race history in a SQLite3 database (horserace.db) with a races table and views for average times (avg_times), horse performance (vwin_counts, vplace_counts, vshow_counts), and net wins (v_true_win).
• Interface: NCURSES menu-driven navigation using arrow keys and Enter, with high-contrast displays and pauses for accessibility.
• Randomization: Horse movements are randomized with xorshift random number generation ensuring no predictable winners. Payouts are randomized per race, ensuring each race is different.
• Statistics: View average race times and top-performing horses before betting, powered by SQLite3 views.

Requirements

• Operating Systems: Tested on Ubuntu 14.04, Debian 12, and Slackware 14. Should port easily to other Linux distributions.
• Dependencies:
• NCURSES: Including libncurses5-dev, libmenu5-dev, and libform5-dev for terminal graphics and menus.
• SQLite3: libsqlite3-dev for database storage.
• GCC: For compilation with -std=c2x.
• Make: For building with the provided Makefile.
• Hardware: Minimal, runs on any Linux terminal (80x24 or larger recom- mended for clear display).

Install dependencies on Debian/Ubuntu:

sudo apt update sudo apt install libncurses5-dev libmenu5-dev libform5-dev libsqlite3-dev

Installation

tar -xzf horserace-v2.0.tar.gz cd horserace-v2.0

make BUILD_TYPE=debug places horserace.db in the current directory. The game runs faster.

make BUILD_TYPE=release sudo make install places the horserace.db in: ~/.horserace/horserace.db

Notes: - The Makefile ensures proper compilation with -Wall, -Wextra, -Wpedantic, and links -lncurses and -lsqlite3. - Debug mode is ideal for testing fast race mode (~16s); release mode uses slow races (~100s).

INSTALL

On Linux systems you can use the make utility by being in the directory where you have the source files entering the correct make command. The make file has options to make clean which will delete the .o and .d files the executable as well as the races.db the sqlite3 database. The make command will require the addition of BUILD_TYPE command line arguments. BUILD_TYPE=debug will create an executable for debugging. BUILD_TYPE=release will create a release executable. The data will be stored in different directories depending on the build type.

RUNNING

To start the program enter the shell command ./horserace in the directory where the executable file is created or any directory where you move the executable produced by the make process. If you build the application from the shell prompt directly (gcc horserace.c -lncurses -lmenu -lsqlite3 -o <executable>) then you must enter your own executable name to run the application.

The program is menu driven. Use the up and down arrow keys to make menu choices and enter to execute your choice. To start you should choose which horse and what place you expect them to finish under "2. Betting". Then use the "3. Race" menu choice to watch the race. The "4. Results" will show you the finish results and payoff. Move the highlight to "Exit" and press enter to leave the program and return to a shell prompt.

Their is some error checking currently and some compile time error checking.

Horse moves are random with no horse given a higher chance of winning. You should not notice any constant winners or losers. The payoffs are randomized and different for each race when you select the <Betting> menu choice. You should first place a bet. Then choose <Race> to watch the race. When the race is finished then choose <Results> to verify your win or loss. The <Exit> choice ends the program.

Running the Game

1. Start: Run the executable:

./horserace

Navigation: Use Up and Down arrow keys to select menu options. Press Enter to to confirm choices. Main menu: 1. Player Name: Enter or edit your name (pre-filled from the last race, e.g., Clem Kadidlehopper). 2. Betting: Select a horse (0–9), finish (Win, Place, Show), and wager ($2.00–$100.00). 3. Race: Watch the race in real-time with animated horse movements. 4. Results: View winners, times (e.g., Win: 0 (18.00)), and your payout (e.g., $500.00 for a 5-to-1 Show bet). 5. Stats: Display average race times and top horses (from SQLite3 views). Exit: Quit to the shell.

Gameplay Flow:

Enter your name (supports backspace for editing). Place a bet (horse, finish, wager). Watch the race (fast or slow mode). Check results for payouts/losses. View stats to inform future bets. Exit when done. Data Storage: Debug: Saves to horserace.db in the current directory. Release: Saves to ~/.horserace/horserace.db and ~/.horserace/horserace.dat. SQLite3 database includes views for analytics (e.g., SELECT * FROM avg_times;).

KNOWN BUGS

Input Handling: Rare NCURSES input lag in some terminals (e.g., older Ubuntu versions). Ensure your terminal supports NCURSES 5 or later.

Database Initialization: If ~/.horserace/ lacks write permissions, horserace.db creation may fail. Ensure permissions with: mkdir -p ~/.horserace chmod 755 ~/.horserace

CHANGE LOG Created on: Aug 10, 2015 - Initial release (v1.0) with NCURSES-based racing, random horse movements Updated on: May 26, 2025 - Release v2.0: Added sqlite3 database integration. Added SQLite3 integration (horserace.db) with races table and views (avg_times, v_true_win, etc.). Introduced fast (~16–21s) and slow (~100–120s) race modes. Enhanced NCURSES interface with high-contrast displays, 2-second pauses, and stats display. Fixed get_player_name() backspace issue for name editing. Streamlined struct gamestate by removing unused fields (whorse, wfinish). Improved Makefile with debug/release builds and SQLite3 linking. Special thanks to Grok AI for code optimization and SQLite3 guidance.