TNO Guangdong Interactive Timeline Generator

This Python script is a powerful tool designed to parse event and localization files from the The New Order: Last Days of Europe mod for Hearts of Iron IV. It intelligently combines the game's narrative logic with its corresponding text to generate a single, interactive Markdown file.

The final output, Guangdong_Interactive_Timeline.md, presents the entire Guangdong storyline as a "choose your own adventure" style document. Users can read through the events and click on hyperlinked choices to jump directly to the next event in that narrative branch, making it an excellent tool for writers, developers, and fans who want to explore the mod's complex story.

Features

• Dual-File Parsing: Reads both the event script (.txt) for logic and the localization file (.txt) for the actual story text.
• Robust Parsing Engine: Uses a brace-counting method to correctly handle complex nested structures (hidden_effect, if blocks, etc.) that would break simpler parsers.
• Interactive Hyperlinks: Automatically detects which event is triggered by a player's choice and creates a clickable link to that event within the Markdown file.
• Structured Narrative Flow: Organizes the events into major acts and branching paths (Prologue, The Silicon Years, The Riots, Epilogues, etc.) for a clear, thematic reading experience.
• Clean & Readable Output: Generates a well-formatted Markdown file with clear headings, blockquotes for event descriptions, and lists for choices.
• Anchor Generation: Creates unique, URL-friendly anchors for every event, ensuring that all links work correctly in any standard Markdown viewer.

Requirements

1. Python 3: You must have Python 3 installed on your system.
2. Event Script File: The main game script file must be present in the same directory and named exactly TNO_Guangdong.txt.
3. Localization File: The file containing the event titles, descriptions, and option text must be in the same directory and named exactly guangdong_plot_text.txt.

How to Use

1. File Setup: Place the following three files in the same folder:

   • main.py (the script provided below)
   • TNO_Guangdong.txt
   • TNO_Guangdong_l_simp_chinese.yml

2. Run the Script: Open a terminal or command prompt, navigate to the folder containing the files, and execute the following command:

   python main.py

3. Find the Output: The script will print its progress to the console. When it's finished, a new file named Guangdong_Interactive_Timeline.md will be created in the same folder. You can open this file with any Markdown-compatible viewer (e.g., VS Code, Obsidian, Typora, or directly on GitHub).

Code Breakdown

The script is divided into several key functions that work together to produce the final output.

parse_localization_file(filepath)

This function is responsible for reading the plot text.

• It opens TNO_Guangdong_l_simp_chinese.yml.
• It iterates through each line, splitting it at the first colon (:).
• The part before the colon is the key (e.g., guangdong.1.t), and the part after is the value (the story text).
• It cleans up the text by removing surrounding quotes and converting \n characters into actual newlines.
• It returns a dictionary mapping every key to its corresponding text.

parse_events_file_with_links(filepath)

This is the core parsing engine for the event logic.

• It reads the entire TNO_Guangdong.txt script file.
• It uses a brace-counting loop to reliably identify the start and end of every country_event = { ... } block, correctly handling any level of nested braces inside.
• For each event block, it extracts:
  • The event id.
  • The localization keys for the title and desc.
  • It then uses another brace-counting loop to parse each option = { ... } block within that event.
  • Inside each option, a flexible regular expression (re.DOTALL) finds the country_event = { id = ... } call, no matter how deeply it's nested (e.g., inside hidden_effect).
  • It returns a dictionary where each event id maps to its title key, description key, and a list of its options, with each option containing its text key and the ID of the next event it triggers.

get_timeline_structure(all_event_ids)

This function provides the high-level narrative structure for the final document.

• It takes a list of all event IDs found in the script.
• It uses the filter_ids helper function to group related events based on their prefixes (e.g., all guangdong_sony... events go together).
• It returns a structured dictionary that organizes the story into acts and branching paths, which is used to generate the main headings in the Markdown file.

create_anchor(text)

A small but crucial utility function.

• It takes a string (like an event title) and converts it into a valid, URL-friendly anchor ID for use in Markdown hyperlinks (e.g., "The Four Companies" becomes the-four-companies).
• This ensures that the [link text](#anchor) syntax works correctly.

write_markdown_timeline(...)

This function assembles the final interactive document.

• It first iterates through all parsed events to pre-generate a unique anchor for every single event ID.
• It then iterates through the structure dictionary provided by get_timeline_structure().
• For each section and subsection, it writes the appropriate Markdown heading (# or ##).
• For each event ID in the section, it looks up its data in the events_data dictionary and its text in the localization_data dictionary.
• It formats the title, description, and options.
• When formatting an option, it checks if it has a next_event ID. If it does, it creates a hyperlink pointing to that event's pre-generated anchor.
• If an option has no direct country_event link (because the outcome is conditional or complex), it is written as plain text.

Example Output Snippet

The script will produce a file where each event is formatted like this:

### 四家公司 <a name="四家公司-guangdong.3"></a>
`Event ID: guangdong.3`

> 铃木和他的下属们发现，在他们的管辖范围内，有四家日本企业巨头拥有实际上的治权。由于东京方面在《关于建立广东联合行政区的条约》中给予了它们几乎无限的自由，这四家公司及其领导人已经成为了广东的无冕之王。

- **[继续……](#安田银行的方式-guangdong.4)**

---