eagle0/docs/RENAMING_A_PROVINCE.md

Renaming a Province

This document explains the steps required to rename a province in Eagle0.

Files to Modify

1. Province Map TSV (Server Source of Truth)

File: src/main/resources/net/eagle0/eagle/province_map.tsv

This is the primary source of province data. Each row contains:

• Province ID
• Province name
• Neighbor IDs
• Neighbor directions
• Province name (repeated)
• Neighbor names (dot-separated)
• Starting food

You need to:

1. Change the province name in its own row (columns 2 and 5)
2. Update the neighbor name references in all neighboring provinces (column 6)

Example: To rename "Fluria" to "NewName", you would need to update:

• Line 26: The Fluria row itself
• Lines 5, 10, 18, 24, 27, 38, 41: All provinces that list Fluria as a neighbor

2. LLM Map Description

File: src/main/scala/net/eagle0/eagle/library/actions/llm_prompt_generators/MapDescription.scala

This file contains a hardcoded geographic description of the map used in LLM prompts for generating narrative text. Update any references to the old province name.

3. Client Centroids JSON

File: src/main/csharp/net/eagle0/clients/unity/eagle0/Assets/Eagle/centroids.json

This JSON file contains province metadata used for map rendering (centroid positions, areas, orientations). Each entry has a name field that should be updated to match.

Note: The actual province name displayed to players comes from the server via the ProvinceView proto, not from this file. However, this file should be kept in sync for consistency and because it may be used for map label positioning.

4. Test Files

File: src/test/scala/net/eagle0/eagle/library/util/validations/RuntimeValidatorTest.scala

Update any test strings that reference the old province name.

How Province Names Flow to the Client

Province names are sent from the Eagle server to the Unity client via the ProvinceView protobuf message:

message ProvinceView {
    int32 id = 1;
    string name = 6;  // <-- Province name sent from server
    ...
}

The server reads province names from province_map.tsv at startup. The client receives names through the proto and displays them via province.Name in C# code. This means:

• Changing the TSV automatically updates what clients see
• No C# code changes are needed (the code uses province.Name generically)
• The centroids.json name field is for map rendering/positioning, not display

Files That Do NOT Need Changes

• Hero backstory TSV files (heroes.tsv, generated_heroes.tsv) - These don't contain province name references
• C# client code - Uses province.Name from the server proto, not hardcoded names
• Proto definitions - No province names are hardcoded in protos

Checklist

• Update province_map.tsv - province's own row
• Update province_map.tsv - all neighbor references
• Update MapDescription.scala
• Update centroids.json
• Update any test files with province name references
• Build and run tests: bazel test //src/test/scala/...