Skip to content

Commit 8c53747

Browse files
TaranDahlTaranDahl
committed
Update copilot-instructions.md
1 parent 56a9f18 commit 8c53747

2 files changed

Lines changed: 254 additions & 0 deletions

File tree

  • .trae/skills
    • 撰写文档-write-documentation
    • 生成ini标签-generate-ini-tag

‎.trae/skills/撰写文档-write-documentation/SKILL.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
name: 撰写文档 Write Documentation
3+
description: "### Write Documentation\n\nThis command is invoked when the code changes for a feature or bugfix are complete on a branch (branched from `develop`) and documentation is the only remaining task. The AI should discover what changed, categorize it, and write the appropriate documentation entries."
4+
---
5+
6+
#### Workflow
7+
8+
**Step 0: Determine the author**
9+
10+
Use `git log develop...HEAD --format="%an <%ae>"` to list commits on the current branch that are not in `develop`. If the branch has extra commits, use the author name(s) from those commits as the user's identity for `CREDITS.md` and `Whats-New.md`. If there are no extra commits or the author cannot be determined from commit information, ask the user directly for their identity before proceeding.
11+
12+
**Step 1: Discover what changed**
13+
14+
Run `git diff develop...HEAD --stat` to see which files were modified. Then inspect the diffs in detail using `git diff develop...HEAD` (or `git diff develop...HEAD -- <specific files>`) to understand the nature of each change. Key things to identify:
15+
- New/changed INI keys (tags) — look for `.Read(exINI, ...)` calls in `LoadFromINIFile` / `LoadBeforeTypeData` etc.
16+
- New/changed hooks — look for `DEFINE_HOOK`, `DEFINE_JUMP`, `DEFINE_PATCH` macros.
17+
- New types/classes — look for new files in `src/New/` or new `ExtData` classes.
18+
- Whether the change is a new feature, an enhancement of existing behavior, a bugfix, a UI change, an AI/scripting change, or something miscellaneous.
19+
20+
**Step 2: Categorize the change**
21+
22+
Determine which doc pages need updating:
23+
24+
| Change type | Where to document |
25+
|-------------|------------------|
26+
| New feature (brand new functionality) | New `### ` section in the appropriate primary doc page, inserted in **dictionary (alphabetical) order** among existing sibling `### ` headings |
27+
| Enhancement of existing game behavior that adds new INI tags | New `### ` section in the appropriate primary doc page, likewise in alphabetical order |
28+
| Enhancement/bugfix of existing game behavior with **no new INI tags** | A bullet point under `## Bugfixes and miscellaneous` in `docs/Fixed-or-Improved-Logics.md` |
29+
| User interface change (new hotkey, display, sidebar, tooltip) | `docs/User-Interface.md` |
30+
| AI, scripting, trigger, or mapping change | `docs/AI-Scripting-and-Mapping.md` |
31+
| Uncategorized change | `docs/Miscellanous.md` |
32+
| New user setting in RA2MD.INI | `docs/Whats-New.md` (under "New user settings") |
33+
34+
Primary doc page mapping:
35+
- Most game logic features → `docs/New-or-Enhanced-Logics.md`
36+
- Within this file, `## ` headings are categories (e.g., `## Buildings`, `## Projectiles`, `## Warheads`). Place new `### ` sections under the appropriate category, sorted alphabetically.
37+
38+
Additionally, every non-trivial change requires:
39+
- **`docs/Whats-New.md`** — changelog entry.
40+
- **`CREDITS.md`** — credit the author.
41+
42+
**Step 3: Draft the documentation text — user review required before writing**
43+
44+
Before writing any documentation, draft the descriptive text and present it to the user for review. Use the following format for the draft:
45+
46+
```
47+
### <Feature Name>
48+
49+
- <Brief meaning of the feature.>
50+
- (tab-indented) <INI key> controls/determines/is used for <explanation>.
51+
```
52+
53+
Two styles for the first bullet point:
54+
- **New feature** (brand new functionality):
55+
```
56+
- Now you can <do something>. (新功能)
57+
```
58+
- **Enhancement of existing behavior** (patches/improves vanilla logic):
59+
```
60+
- In vanilla, <describe the problem>. Now you can <describe the fix/enhancement>.
61+
```
62+
63+
Wait for the user to approve the drafted text before proceeding to write it into the actual doc files.
64+
65+
**Step 4: Write the main documentation**
66+
67+
After user approval, write the approved text into the appropriate doc file. For sections in `docs/New-or-Enhanced-Logics.md` or similar, insert the new `### ` section in alphabetical order among existing sibling headings under the correct `## ` category. Look at existing sibling `### ` headings to determine the correct insertion point.
68+
69+
Continue with the INI code block following existing conventions:
70+
71+
```markdown
72+
In `rulesmd.ini`:
73+
```ini
74+
[SECTION] ; ObjectType
75+
KeyName=default ; accepted type
76+
KeyName.WithDots=default ; accepted type with optional explanation
77+
```
78+
```
79+
80+
Key rules for INI documentation:
81+
- Use ` ```ini ` fenced code blocks.
82+
- Section header comment format: `[SOMENAME]` followed by spaces then `; ObjectType` (e.g., `; BuildingType`, `; TechnoType`, `; WarheadType`, `; SuperWeaponType`).
83+
- For global sections use the literal section name: `[General]`, `[AudioVisual]`, `[CombatDamage]`, `[Radiation]`, `[AI]`, etc.
84+
- Key name, equals sign, default value (or blank if empty), spaces, semicolon, type description.
85+
- Boolean types are documented as `; boolean`.
86+
- Integer types as `; integer`.
87+
- Floating point types as `; double` or `; float`.
88+
- Pointer types as `; AnimType` (just the game class name, not full C++ type).
89+
- List types as `; list of TechnoType` etc.
90+
- If the INI key name contains dots, it maps naturally (e.g. `KeyName.SubKey` stays as-is in docs).
91+
92+
When there are many related keys, group them logically within the same section and INI block. Put them in the order they appear in the INI section.
93+
94+
**Step 5: Chinese translation**
95+
96+
After the English documentation has been written and confirmed, produce a Chinese translation of the new section(s). Present the Chinese text to the user for review and confirmation. Update the corresponding `.po` files in `docs/locale/zh_CN/LC_MESSAGES/` after the user approves the translation.
97+
98+
**Step 6: Write `docs/Whats-New.md` entry**
99+
100+
Whats-New entries go under the `### Version TBD (develop branch nightly builds)` section. Use the author identity determined in Step 0. The entry should be a bullet point briefly describing the change and how it might affect existing mods:
101+
102+
```markdown
103+
- <description of what changed and what modders need to do to adapt> (by <AuthorName>)
104+
```
105+
106+
If new INI keys are user-facing settings in `RA2MD.INI`, also add them under the `### New user settings in RA2MD.INI` section:
107+
```ini
108+
[Phobos]
109+
NewKeyName=true ; boolean
110+
```
111+
112+
If INI keys were renamed, add entries under `### Changed tags` using the format seen in existing entries:
113+
```markdown
114+
- `[Section] -> OldName` -> `[Section] -> NewName`
115+
```
116+
117+
**Step 7: Write `CREDITS.md` entry**
118+
119+
Use the author identity determined in Step 0. Find the author's section in `CREDITS.md`. If the author doesn't have a section yet, create one. Add a bullet describing the contribution:
120+
121+
```markdown
122+
- **AuthorName (GitHubUsername)**:
123+
- Feature description matching the phrasing used in other entries
124+
```
125+
126+
Do not skip the CREDITS entry unless the user explicitly says to skip it.
127+
128+
**Step 8: Review and confirm**
129+
130+
After writing all entries, present a summary to the user showing which files were modified and what was added.

‎.trae/skills/生成ini标签-generate-ini-tag/SKILL.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
name: 生成INI标签 Generate INI tag
3+
description: "A \"tag\" is an INI key that generally corresponds to a C++ property. Defining a tag requires modifications in four places within the target `ExtData` class: **declaration**, **initialization**, **serialization**, and **INI loading**. If the user does not provide all information explicitly, the AI should infer the missing pieces, present them to the user for confirmation, and only proceed after approval."
4+
---
5+
6+
#### 1. Determine the Class
7+
8+
Game entities have **instance classes** (e.g., `BuildingClass`) and **static type classes** (e.g., `BuildingTypeClass`). Tags are almost always defined in the static type class's `ExtData` — when the user says "add a tag for buildings", they mean `BuildingTypeExt::ExtData`. Same pattern applies:
9+
10+
| User says | Corresponding ExtData |
11+
|-----------|----------------------|
12+
| Building / BuildingType | `BuildingTypeExt::ExtData` |
13+
| Vehicle / Unit / UnitType | `UnitTypeExt::ExtData` (or `TechnoTypeExt::ExtData`) |
14+
| Infantry / InfantryType | `InfantryTypeClass` → `TechnoTypeExt::ExtData` |
15+
| Aircraft / AircraftType | `AircraftTypeClass` → `TechnoTypeExt::ExtData` |
16+
| Warhead | `WarheadTypeExt::ExtData` |
17+
| Weapon | `WeaponTypeExt::ExtData` |
18+
| Bullet / Projectile | `BulletTypeExt::ExtData` |
19+
| SuperWeapon / SW | `SWTypeExt::ExtData` |
20+
| Animation / Anim | `AnimTypeExt::ExtData` |
21+
| Particle | `ParticleTypeExt::ExtData` |
22+
| Terrain / TerrainType | `TerrainTypeExt::ExtData` |
23+
| Overlay / OverlayType | `OverlayTypeExt::ExtData` |
24+
| Global / Rules | `RulesExt::ExtData` |
25+
26+
Note: `TechnoTypeExt::ExtData` is the **common base class** extension for `BuildingType`, `UnitType`, `InfantryType`, and `AircraftType`. If a tag applies to all Techno types, place it in `TechnoTypeExt`; if it applies only to a specific subtype, place it in the corresponding subclass Ext (e.g., buildings only → `BuildingTypeExt`).
27+
28+
#### 2. Determine the Section
29+
30+
- **Non-global tags**: Read from `pSection` (the INI section matching the instance ID/name) inside `LoadFromINIFile`. Determine whether to use `pSection` or `pArtSection`:
31+
- `pSection` = `pThis->ID` — reads from the identically-named section in `rulesmd.ini`. The vast majority of tags go here.
32+
- `pArtSection` = `pThis->ImageFile` — reads from the identically-named section in `artmd.ini`, using `INI_Art` / `exArtINI`. Generally used for visual, graphical, or animation-related tags. Check whether the class's `LoadFromINIFile` defines a `pArtSection` variable and `exArtINI` to see if this is supported.
33+
- **Global tags**: For `RulesExt::ExtData`, read from fixed global sections such as `GameStrings::General` (`[General]`), `GameStrings::CombatDamage` (`[CombatDamage]`), `GameStrings::Radiation` (`[Radiation]`), `GameStrings::AudioVisual` (`[AudioVisual]`), `GameStrings::AI` (`[AI]`), etc. Infer the appropriate section based on the key name's semantics.
34+
35+
#### 3. Determine the Key Name
36+
37+
The INI key name specified by the user. **Critical conversion rule: dots `.` in the key name become underscores `_` in the C++ property name.**
38+
39+
For example: `"Factory.IsSuper"` → C++ property name `Factory_IsSuper`
40+
41+
#### 4. Determine the Type
42+
43+
Infer the C++ type based on semantics. Common types and their wrappers:
44+
45+
| Semantics | C++ Type | Wrapper |
46+
|-----------|---------|---------|
47+
| Boolean on/off switch | `bool` | `Valueable<bool>` |
48+
| Integer (count, frames, int percentage) | `int` | `Valueable<int>` |
49+
| Floating point (ratio, multiplier, speed) | `double` | `Valueable<double>` |
50+
| In-game distance (Lepton) | `Leptons` | `Valueable<Leptons>` |
51+
| Coordinate | `CoordStruct` / `Point2D` | `Valueable<CoordStruct>` |
52+
| Color | `ColorStruct` | `Valueable<ColorStruct>` |
53+
| Nullable (omitting means use default logic) | any | `Nullable<T>` |
54+
| List (comma-separated values) | `std::vector<T>` | `ValueableVector<T>` |
55+
| Pointer to another game type | `WeaponTypeClass*` etc. | `Valueable<WeaponTypeClass*>` |
56+
| Index lookup (sounds etc.) | see `ValueableIdx` | `ValueableIdx<VocClass>` |
57+
| Enum | game enum | `Valueable<AffectedHouse>` etc. |
58+
59+
**Inference rules:**
60+
- Key name contains `Is`/`Can`/`Allow`/`Use`/`Has`/`Enable`/`Disable` → likely `Valueable<bool>`
61+
- Key name contains `Amount`/`Count`/`Max`/`Min`/`Delay`/`Rate`/`Frame` (integer) → likely `Valueable<int>`
62+
- Key name contains `Factor`/`Mult`/`Percent`/`Speed`/`Ratio`/`Chance` → likely `Valueable<double>`
63+
- Key name contains `Type` (singular pointer) → `Valueable<SomeTypeClass*>`
64+
- Key name contains `Types` (plural) → `ValueableVector<SomeTypeClass*>`
65+
- When unsure about optionality, default to `Valueable<T>` (required); use `Nullable<T>` if omitting is semantically valid.
66+
67+
#### 5. Implementation Steps
68+
69+
Modify the `Body.h` and `Body.cpp` of the target ExtData. Follow these four steps:
70+
71+
**A. Declare the property (Body.h → ExtData public section)**
72+
73+
Follow existing declaration style, e.g.:
74+
```cpp
75+
Valueable<bool> Factory_IsSuper;
76+
```
77+
78+
**B. Initialize the property (Body.h → ExtData constructor initializer list)**
79+
80+
Add a default value in the constructor, matching the existing format (comma-first, aligned):
81+
```cpp
82+
, Factory_IsSuper { false }
83+
```
84+
85+
**C. Register in serialization (Body.cpp → Serialize function)**
86+
87+
Insert into the `Stm` chain in `Serialize(T& Stm)`, ordered alphabetically or logically:
88+
```cpp
89+
.Process(this->Factory_IsSuper)
90+
```
91+
92+
**D. INI loading (Body.cpp → LoadFromINIFile function)**
93+
94+
Based on the section determined in step 2, choose `exINI` or `exArtINI`, and `pSection` or `pArtSection`:
95+
```cpp
96+
// From rulesmd.ini (most common)
97+
this->Factory_IsSuper.Read(exINI, pSection, "Factory.IsSuper");
98+
99+
// From artmd.ini (visual/graphical)
100+
this->Factory_IsSuper.Read(exArtINI, pArtSection, "Factory.IsSuper");
101+
102+
// Global tag example (RulesExt)
103+
this->Factory_IsSuper.Read(exINI, GameStrings::General, "Factory.IsSuper");
104+
```
105+
106+
If the property is a pointer to another game type (e.g., `Valueable<WeaponTypeClass*>`), use `.Read<true>` to enable auto-creation:
107+
```cpp
108+
this->SomeWeapon.Read<true>(exINI, pSection, "SomeWeapon");
109+
```
110+
111+
#### 6. Full Example
112+
113+
User says: "add a tag called `Factory.IsSuper` for buildings"
114+
115+
Inference process:
116+
- Class: `BuildingTypeExt::ExtData` ("buildings" → building type static data)
117+
- Section: `pSection` (not visual-related)
118+
- Key: `Factory.IsSuper` → property name `Factory_IsSuper`
119+
- Type: `Valueable<bool>` (contains `Is`, boolean semantics)
120+
- Default: `false` (conservative default)
121+
122+
After confirmation, modify:
123+
- [Body.h](file:///f:/RA2%20Engine%20Extension/MJobos/src/Ext/BuildingType/Body.h): declaration + initialization
124+
- [Body.cpp](file:///f:/RA2%20Engine%20Extension/MJobos/src/Ext/BuildingType/Body.cpp): Serialize + LoadFromINIFile

0 commit comments

Comments
 (0)