Metadata-Version: 2.4
Name: tinvictatools
Version: 0.1.0
Summary: Tools to work with the 4X video game Terra Invicta.
Home-page: https://github.com/veogam/tinvictatools
Author: veo
Author-email: veogam@icloud.com
License: MIT
Project-URL: Bug Tracker, https://github.com/veogam/tinvictatools/issues
Project-URL: Documentation, https://tinvictatools.readthedocs.io
Project-URL: Source, https://github.com/veogam/tinvictatools
Keywords: terra invicta,game tools,save game,4x strategy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openpyxl
Requires-Dist: pyyaml
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mkdocs; extra == "dev"
Requires-Dist: mkdocs-material; extra == "dev"
Requires-Dist: mkdocstrings[python]; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# tinvictatools

[![Tests](https://github.com/veogam/tinvictatools/actions/workflows/ci.yml/badge.svg)](https://github.com/veogam/tinvictatools/actions/workflows/ci.yml)

Tools for the 4X video game [Terra Invicta](https://store.steampowered.com/app/1176470/Terra_Invicta/).

## Features

### Current

- **Site Report** — a command that reads your save file and writes an Excel spreadsheet listing every prospected hab site with its resources and a customizable score.

### Future

- Exporting / Importing template sets for Hab, Ships, and National Priorities into save games with intelligent technology checking (planned).
- Watch the save file and alert on new orgs or councilors matching specific trait criteria
- Automatic Hab Naming according to rules parsed by user-specified strings in a custom Domain Specific Language (DSL) built with Abstract Syntax Trees according to rules based on resource, location, module data, etc.
- Assistance of drive analysis using parsed game data.
- New player hints and warnings based on save game analysis with a customizable extensible modular ruleset.
- A GUI or web app — contributions welcome, especially from those with frontend experience.

---

## Installation

### Step 1 — Install Python

1. Go to [python.org/downloads](https://www.python.org/downloads/) and click **Download Python 3.x.x** (the big yellow button).
2. Run the installer.
3. **Important:** On the first screen, check the box that says **"Add python.exe to PATH"** before clicking Install Now.

    ![Python installer PATH checkbox](https://docs.python.org/3/_images/win_installer.png)

4. Click **Install Now** and let it finish.

To confirm it worked, open a terminal:

- **Windows 11:** Right-click the Start button and select **Terminal**
- **Older Windows:** Press `Win + R`, type `cmd`, and press Enter

Then run:

```batch
python --version
```

You should see something like `Python 3.12.4`.

> **Windows 11 only:** If running `python` opens the Microsoft Store instead, go to **Settings → Apps → Advanced app settings → App execution aliases** and turn off the two **python** toggles. Then close and reopen the terminal and try again.

If you get an error, close and reopen the terminal and try again.

### Step 2 — Install tinvictatools

In the same terminal window, run:

```batch
pip install tinvictatools
```

You'll see a stream of text as it downloads. When the prompt returns you're done.

---

## Generating a Site Report

Open a terminal (Windows 11: right-click Start → **Terminal**; older Windows: `Win + R` → `cmd`) and run:

```batch
tinvictatools-site-report
```

That's it. The tool finds your most recent autosave automatically
(`Documents\My Games\TerraInvicta\Saves\Autosave.gz`) and writes
**SiteReport.xlsx** in whatever folder the terminal is currently in.
Open it in Excel or LibreOffice Calc.

### What's in the spreadsheet

The **Sites** sheet has one row per prospected hab site:

| Column | Description |
| --- | --- |
| Name | Hab site name |
| Site | The body it's on (e.g. Mars, Ceres) |
| Location | Region of the solar system |
| Water / Vols / Metal / Nobles / Fissiles | Monthly resource income |
| Score | Weighted sum of resources (adjustable — see below) |
| Most | Which resource contributes most to the score |
| Settled | Whether a hab has been built here |
| Faction | Which faction built it |

The **Weights** sheet controls the score formula. Change the numbers in row 2
and the Score column updates automatically — no need to re-run the tool.

### Options

#### Save a different filename or location

```batch
tinvictatools-site-report --output C:\Users\YourName\Desktop\MyReport.xlsx
```

#### Use a different save file

```batch
tinvictatools-site-report "C:\Users\YourName\Documents\My Games\TerraInvicta\Saves\Quicksave.gz"
```

#### Show daily income instead of monthly

```batch
tinvictatools-site-report --daily
```

#### Include all hab sites, not just prospected ones

```batch
tinvictatools-site-report --all-sites
```

#### Combine options

```batch
tinvictatools-site-report --all-sites --output report.xlsx "C:\path\to\save.gz"
```

### Customising the default weights

Create a file called `config.yaml` at `C:\Users\YourName\.config\tinvictatools\config.yaml`
with content like:

```yaml
weights:
  Water: 1.0
  Vols: 1.0
  Metal: 1.0
  Nobles: 5.0
  Fissiles: 10.0
```

Adjust the numbers to match your priorities. The tool loads this file automatically on every run.

---

## Troubleshooting

### `tinvictatools-site-report` is not recognized**

Python's Scripts folder isn't on your PATH. Try closing and reopening the terminal.
If that doesn't help, reinstall Python and make sure to check **"Add python.exe to PATH"**.
On Windows 11, also check that the Python App execution aliases are disabled (see the note in Step 1).

### `No such file or directory` for the save file**

The tool looks for the autosave at the default location. If you moved your saves folder,
pass the path explicitly:

```powershell
tinvictatools-site-report "C:\path\to\your\Autosave.gz"
```

### The spreadsheet opens but columns look wrong

Make sure to open the file in Excel or LibreOffice Calc, not a text editor.

---

## For developers

See the [API documentation](https://tinvictatools.readthedocs.io) for library usage and contributing information.
