initiative-tracker 0.1.0__tar.gz

initiative_tracker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Wagenvoort
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

initiative_tracker-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: initiative-tracker
+Version: 0.1.0
+Summary: A simple cli based initiative tracker for dnd or other ttrpgs
+License-Expression: MIT
+License-File: LICENSE
+Author: Quaeren
+Author-email: ldwagenvoort@hotmail.com
+Requires-Python: >=3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: questionary (>=2.1.1,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Initiative Tracker for TTRPGS
+A simple command line interface for running a initiative tracker in the terminal. You can create an encounter, add combatants, roll initiative, track health and save encounters for later use.
+
+## Features
+- **Combatant Mangement** Add or remove players, enemies or allies in an encounter
+- **Automatic Turn Tracking** After letting the program roll the initiative it autmatically tracks whoose turn it is
+- **Health Management** Add or remove health via the damage and heal funcitons
+- **Save and Load** Save and load encounters between sessions for quick and easy playthroughs
+
+## How to Use
+### Main menu
+When the application starts, you can choose to:
+- **Start new encounter:** Create an empty encounter.
+- **Load** encounter:** Load the saved encounter.
+- **Exit:** Close the application.
+
+### Managing an encounter
+Once an encounter has been created or loaded, the encounter menu provides the following options:
+- **Add combatant:** Enter a name, maximum hit points, initiative modifier, and combatant type.
+- **Remove combatant:** Select combatants to remove from the encounter.
+- **View turn order:** Sort combatants by initiative and display their current health and initiative.
+- **Roll initiative:** Roll initiative for every combatant.
+- **Start encounter:** Open the turn-order menu and begin managing combat.
+- **Save encounter:** Save the encounter's current state to the database.
+- **Exit:** Return to the main menu.
+
+During an encounter, the currently active combatant is marked with an arrow. You can advance to the next turn, reset the round counter, or select a combatant to perform a health-related action.
+
+### Actions on a combatant
+Once you select a combatant you are presented with the option to input a command, the following commands are allowed:
+- **damage** after inputting enter a value and the corresponding health will be removed
+- **heal** after inputting enter a value and the corresponding health will be healed
+- **set** after inputting manually set and initiative value for the combatant
+- **exit** after inputting press enter again and exit this menu
+
+## License
+MIT

initiative_tracker-0.1.0/README.md

@@ -0,0 +1,37 @@
+# Initiative Tracker for TTRPGS
+A simple command line interface for running a initiative tracker in the terminal. You can create an encounter, add combatants, roll initiative, track health and save encounters for later use.
+
+## Features
+- **Combatant Mangement** Add or remove players, enemies or allies in an encounter
+- **Automatic Turn Tracking** After letting the program roll the initiative it autmatically tracks whoose turn it is
+- **Health Management** Add or remove health via the damage and heal funcitons
+- **Save and Load** Save and load encounters between sessions for quick and easy playthroughs
+
+## How to Use
+### Main menu
+When the application starts, you can choose to:
+- **Start new encounter:** Create an empty encounter.
+- **Load** encounter:** Load the saved encounter.
+- **Exit:** Close the application.
+
+### Managing an encounter
+Once an encounter has been created or loaded, the encounter menu provides the following options:
+- **Add combatant:** Enter a name, maximum hit points, initiative modifier, and combatant type.
+- **Remove combatant:** Select combatants to remove from the encounter.
+- **View turn order:** Sort combatants by initiative and display their current health and initiative.
+- **Roll initiative:** Roll initiative for every combatant.
+- **Start encounter:** Open the turn-order menu and begin managing combat.
+- **Save encounter:** Save the encounter's current state to the database.
+- **Exit:** Return to the main menu.
+
+During an encounter, the currently active combatant is marked with an arrow. You can advance to the next turn, reset the round counter, or select a combatant to perform a health-related action.
+
+### Actions on a combatant
+Once you select a combatant you are presented with the option to input a command, the following commands are allowed:
+- **damage** after inputting enter a value and the corresponding health will be removed
+- **heal** after inputting enter a value and the corresponding health will be healed
+- **set** after inputting manually set and initiative value for the combatant
+- **exit** after inputting press enter again and exit this menu
+
+## License
+MIT

initiative_tracker-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "initiative-tracker"
+version = "0.1.0"
+description = "A simple cli based initiative tracker for dnd or other ttrpgs"
+authors = [
+    {name = "Quaeren",email = "ldwagenvoort@hotmail.com"}
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "questionary (>=2.1.1,<3.0.0)"
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

initiative_tracker-0.1.0/src/initiative_tracker/CLI.py

@@ -0,0 +1,182 @@
+import questionary
+from questionary import Separator
+from .tracker import Database, Encounter, Combatant
+import subprocess
+import os
+
+
+def clear_screen():
+    subprocess.run(
+        ["cmd", "/c", "cls"] if os.name == "nt" else ["clear"], check=False)
+
+def sub_menu_questions():
+    clear_screen()
+
+    return questionary.select(
+        "Please choose an action to do:",
+        choices=[
+            "Add combatant",
+            "Remove combatant",
+            "View turn order",
+            "Roll initiative",
+            "Start encounter",
+            "Save encounter",
+            "Exit"
+        ], qmark="", instruction=None, use_shortcuts=True).ask() or "do nothing"
+
+def remove_combatant_cli(encounter):
+        clear_screen()
+        
+        choices = []
+        for i, combatant in enumerate(encounter.combatant_list):
+            name = f"{combatant}"
+
+            choices.append(questionary.Choice(
+                title=name,
+                value=combatant))
+        choices.append("Exit")
+
+        choice = questionary.checkbox("Please select combatants to be removed:", choices=choices, qmark="", instruction=None, use_shortcuts=True).ask() or []
+
+        if "Exit" in choice:
+           pass 
+
+        for item in choice:
+            encounter.remove_combatant(item)
+        print("Succesfully removed all selected combatants combatants")
+
+def choice_menu(choice, encounter):
+        clear_screen()
+        
+        match choice:
+            case "Add combatant":
+                name = questionary.text("Name: ", qmark="", instruction=None).ask()
+                health = int(questionary.text("Health: ", qmark="", instruction=None).ask())
+                init_mod = int(questionary.text("Initiative modifier: ", qmark="", instruction=None).ask())
+                type = questionary.select(
+                    "Select combatant tupe: ",
+                    choices=["player", "enemy", "ally"], qmark="", instruction=None, use_shortcuts=True).ask()
+
+                encounter.add_combatant(Combatant(name, health, init_mod, type))
+                print(f"Combatant: {name} added succesfully")
+                return None
+            case "Remove combatant":
+                remove_combatant_cli(encounter)
+                return None
+            case "View turn order":
+                clear_screen()
+                encounter.sort_list()
+                encounter.print_turn_order()
+                questionary.press_any_key_to_continue().ask()
+                return None
+            case "Roll initiative":
+                encounter.roll_all_initiative()
+                return None
+            case "Start encounter":
+                return "Start"
+            case "Save encounter":
+                return "Save"
+            case "Exit":
+                return "Exit"
+
+def active_encounter(encounter):
+    while True:
+        clear_screen()
+        choices = []
+
+        for i, combatant in enumerate(encounter.combatant_list):
+            name = f"▶ {combatant}" if i == encounter.active_combatant_index else f"  {combatant}"
+
+            choices.append(questionary.Choice(
+                title=name,
+                value=combatant
+            ))
+        choices.append(Separator())
+        choices.append("  Reset round number")
+        choices.append("  End Turn")
+        choices.append("  Exit")
+
+        print(f"Round Number: {encounter.round_number}")
+        choice = questionary.select("Turn Order:", choices=choices, qmark="", instruction=None, use_shortcuts=True).ask() or "do nothing"
+
+        if choice == "  End Turn":
+            encounter.advance_turn()
+            continue
+        elif choice == "  Exit":
+            break
+        elif choice == "  Reset round number":
+            encounter.reset_round_number()
+            continue
+        else:
+            action = input(choice).strip()
+            value = input("Value: ").strip()
+            if action.lower() == "damage":
+                encounter.combatant_list[encounter.combatant_list.index(choice)].damage(int(value))
+            elif action.lower() == "heal":
+                encounter.combatant_list[encounter.combatant_list.index(choice)].heal(int(value))
+            elif action.lower() == "set":
+                encounter.combatant_list[encounter.combatant_list.index(choice)].set_init(int(value))
+            elif action.lower() == "exit":
+                continue
+
+
+
+
+def main():
+    database = Database()
+    database.create_tables()
+    clear_screen()
+
+    while True:
+        print("===========================================================================================")
+        print(""" ▄▄▄ ▗▄ ▗▖ ▄▄▄ ▗▄▄▄▖ ▄▄▄   ▄  ▗▄▄▄▖ ▄▄▄ ▗▖ ▗▖▗▄▄▄▖     ▗▄▄▄▖▗▄▄▖   ▄    ▄▄ ▗▖ ▄▖▗▄▄▄▖▗▄▄▖ 
+ ▀█▀ ▐█ ▐▌ ▀█▀ ▝▀█▀▘ ▀█▀  ▐█▌ ▝▀█▀▘ ▀█▀ ▝█ █▘▐▛▀▀▘     ▝▀█▀▘▐▛▀▜▌ ▐█▌  █▀▀▌▐▌▐▛ ▐▛▀▀▘▐▛▀▜▌
+  █  ▐▛▌▐▌  █    █    █   ▐█▌   █    █   █ █ ▐▌          █  ▐▌ ▐▌ ▐█▌ ▐▛   ▐▙█  ▐▌   ▐▌ ▐▌
+  █  ▐▌█▐▌  █    █    █   █ █   █    █   █ █ ▐███        █  ▐███  █ █ ▐▌   ▐██  ▐███ ▐███ 
+  █  ▐▌▐▟▌  █    █    █   ███   █    █   ▐█▌ ▐▌          █  ▐▌▝█▖ ███ ▐▙   ▐▌▐▙ ▐▌   ▐▌▝█▖
+ ▄█▄ ▐▌ █▌ ▄█▄   █   ▄█▄ ▗█ █▖  █   ▄█▄  ▐█▌ ▐▙▄▄▖       █  ▐▌ ▐▌▗█ █▖ █▄▄▌▐▌ █▖▐▙▄▄▖▐▌ ▐▌
+ ▀▀▀ ▝▘ ▀▘ ▀▀▀   ▀   ▀▀▀ ▝▘ ▝▘  ▀   ▀▀▀  ▝▀▘ ▝▀▀▀▘       ▀  ▝▘ ▝▀▝▘ ▝▘  ▀▀ ▝▘ ▝▘▝▀▀▀▘▝▘ ▝▀ """)
+        print("===========================================================================================")
+        action = (questionary.select("Welcome to tracker, please select from the options below:", 
+            choices=[
+                "Start new encounter",
+                "Load encounter",
+                "Exit"], qmark="", instruction=None, use_shortcuts=True).ask() or "do nothing")
+
+        match action:
+            case "Start new encounter":
+                encounter = Encounter()
+
+                while True:
+                    choice = sub_menu_questions()
+                    check = choice_menu(choice, encounter)
+                    if check == None:
+                        continue
+                    elif check == "Exit":
+                        break
+                    elif check == "Save": 
+                        database.save_encounter(encounter)
+                    elif check == "Start":
+                        active_encounter(encounter)
+            case "Load encounter":
+                encounter  = database.load_encounter()
+
+                while True:
+                    choice = sub_menu_questions()
+                    check = choice_menu(choice, encounter)
+                    if check == None:
+                        continue
+                    elif check == "Exit":
+                        break
+                    elif check == "Save": 
+                        database.save_encounter(encounter)
+                    elif check == "Start":
+                        active_encounter(encounter)
+            case "Exit":
+                clear_screen()
+                break
+            case _:
+                print("No option chosen")
+
+if __name__ == "__main__":
+    main()

initiative_tracker-0.1.0/src/initiative_tracker/tracker.py

@@ -0,0 +1,231 @@
+import random
+import sqlite3
+from pathlib import Path
+
+class Combatant:
+    def __init__(self, name, hp, init_mod, type):
+        self.name = name.strip()
+        self.max_hp = hp
+        self.hp = hp
+        self.init_mod = init_mod # initiative modifer
+        self.init = 0 # set default initiative to zero
+        self.type = type
+
+    def damage(self, value: int) -> None:
+        if value <= 0:
+            raise ValueError("Only positive numbers above zero accepted")
+        else:
+            if (self.hp - value) < 0:
+                self.hp = 0
+            else:
+                self.hp -= value
+            #print(f"{value} damage done to {self.name}. Current HP: {self.hp}")
+
+    def heal(self, value:int) -> None:
+        if value <= 0:
+            raise ValueError("Only positive number above zero accepted")
+        else:
+            if (self.hp + value) > self.max_hp:
+                self.hp = self.max_hp
+            else:
+                self.hp += value
+            #print(f"{value} damage healed for {self.name}. Current HP: {self.hp}")
+        
+    def set_init(self, value:int) -> None:
+        if value > 0 and value < 26:
+            self.init = value
+        else:
+            raise ValueError("Value has to be between 1 and 25")
+        
+    def set_init_mod(self, value:int) -> None:
+        if value >= -5 and value <= 5:
+            self.init_mod = value
+        else:
+            raise ValueError("Value has to be between -5 and 5")
+        
+    def roll_init(self) -> int:
+        init = random.randint(1,20) + self.init_mod
+        if init <= 0:
+            init = 1
+        self.init = init
+        return init
+    
+    def change_name(self, name):
+        if not isinstance(name, str):
+            raise TypeError("Name must be a string")
+        
+        if not name.strip():
+            raise ValueError("Name cannnot be empty")
+        
+        self.name = name.strip()
+
+    def __str__(self):
+        return f"{self.name} ({self.hp}/{self.max_hp}) HP, ({self.init})"
+
+    def __lt__(self, other):
+        return self.init > other.init
+
+class Encounter:
+    def __init__(self):
+        self.combatant_list = []
+        self.active_combatant_index = 0
+        self.round_number = 0
+
+
+    def add_combatant(self, combatant):
+        self.combatant_list.append(combatant)
+
+    def remove_combatant(self, removee):
+        for i, combatant in enumerate(self.combatant_list):
+            if combatant == removee:
+                if self.combatant_list.index(removee) == self.active_combatant_index:
+                    self.active_combatant_index += 1
+                    if self.active_combatant_index > (len(self.combatant_list) - 1):
+                        self.active_combatant_index = 0
+                        self.round_number += 1
+                del self.combatant_list[i]
+
+    def sort_list(self):
+        self.combatant_list.sort()
+        
+    def print_turn_order(self):
+        for mem in self.combatant_list:
+            print(mem)
+
+    def roll_all_initiative(self):
+        for mem in self.combatant_list:
+            mem.roll_init()
+
+    def advance_turn(self):
+        self.active_combatant_index += 1
+
+        if self.active_combatant_index >= len(self.combatant_list):
+            self.active_combatant_index = 0
+            self.round_number += 1
+
+        while self.combatant_list[self.active_combatant_index].hp == 0:
+            self.active_combatant_index += 1
+
+            if self.active_combatant_index >= len(self.combatant_list):
+                self.active_combatant_index = 0
+                self.round_number += 1
+
+    def reset_round_number(self):
+        self.round_number = 0
+
+class Database:
+    def __init__(self, db_name="tracker.db"):
+        self.db_name = db_name
+
+    def check(self):
+        return Path(self.db_name).exists()
+
+    def connect(self):
+        conn = sqlite3.connect(self.db_name)
+        conn.execute("PRAGMA foreign_keys = ON")
+        return conn
+
+    def create_tables(self):
+        with self.connect() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS encounters (
+                    id INTEGER PRIMARY KEY,
+                    round_number INTEGER NOT NULL DEFAULT 0,
+                    active_index INTEGER
+                )
+            """)
+
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS combatants (
+                    id INTEGER PRIMARY KEY,
+                    encounter_id INTEGER NOT NULL,
+                    name TEXT NOT NULL,
+                    max_hp INTEGER NOT NULL,
+                    hp INTEGER NOT NULL,
+                    init_mod INTEGER NOT NULL,
+                    init INTEGER NOT NULL,
+                    type TEXT NOT NULL,
+
+                    FOREIGN KEY (encounter_id)
+                        REFERENCES encounters(id)
+                        ON DELETE CASCADE
+                )    
+            """)
+
+            conn.execute("""
+                INSERT OR IGNORE INTO encounters (id, round_number)
+                VALUES (1, 0)
+            """)
+
+    def save_encounter(self, encounter):
+        with self.connect() as conn:
+            conn.execute("PRAGMA foreign_keys = ON")
+
+            conn.execute("""
+                UPDATE encounters
+                SET round_number = ?, active_index = ?
+                WHERE id = 1
+            """, (encounter.round_number, encounter.active_combatant_index))
+
+            conn.execute("""
+                DELETE FROM combatants
+                WHERE encounter_id = 1
+            """)
+
+            for combatant in encounter.combatant_list:
+                conn.execute("""
+                    INSERT INTO combatants (
+                        encounter_id,
+                        name,
+                        max_hp,
+                        hp,
+                        init_mod,
+                        init,
+                        type    
+                    )
+                    VALUES (1, ?, ?, ?, ?, ?, ?)
+                """, (combatant.name, combatant.max_hp, combatant.hp, combatant.init_mod, combatant.init, combatant.type))
+
+    def load_encounter(self):
+        with self.connect() as conn:
+            conn.row_factory = sqlite3.Row
+
+            encounter_row = conn.execute("""
+                SELECT round_number, active_index
+                FROM encounters
+                WHERE id = 1
+            """).fetchone()
+
+            if encounter_row is None:
+                return None
+
+            encounter = Encounter()
+            encounter.round_number = encounter_row["round_number"]
+
+            rows = conn.execute("""
+                SELECT name, max_hp, hp, init_mod, init, type
+                FROM combatants
+                WHERE encounter_id = 1
+                ORDER BY id
+            """).fetchall()
+
+            for row in rows:
+                combatant = Combatant(
+                    row["name"],
+                    row["max_hp"],
+                    row["init_mod"],
+                    row["type"]
+                )
+
+                combatant.hp = row["hp"]
+                combatant.init = row["init"]
+
+                encounter.add_combatant(combatant)
+
+            active_index = encounter_row["active_index"]
+
+            if active_index is not None:
+                if 0 <= active_index < len(encounter.combatant_list):
+                    encounter.active_combatant_index = active_index
+
+            return encounter