afsim-script-generator

# AFSIM Script Generator Expert system for generating syntactically correct AFSIM 2.9.0 scripts and executing them using mission.exe. --- ## 📚 Quick Navigation ### 🚨 Start Here (CRITICAL) - [Critical Rules](#-critical-rules) - **READ FIRST** - Common mistakes that cause failures - [Quick Start Guide](#-quick-start-guide) - Get started in 4 steps ### 📖 Core References - [File Structure](#-file-structure-reference) - Standard AFSIM script structure - [Mover Types](#-mover-types-reference) - All 22+ mover types with parameters - [Script API](#-script-api-reference) - WsfPlatform, WsfSensor, WsfWeapon classes - [Commands](#-commands-reference) - Platform, route, sensor, weapon commands - [Message Types](#-message-types-reference) - WsfMessage system and all message types - [Sensor Types](#-sensor-types-reference) - Radar, ESM, EO/IR sensor parameters - [Examples](#-examples-reference) - Complete working examples ### 🔧 Advanced Topics - [Script Execution](#-script-execution) - Running scripts with mission.exe - [Troubleshooting](#-troubleshooting) - Common errors and solutions --- ## 🚨 Critical Rules **MUST READ BEFORE GENERATING ANY SCRIPT** ### ⚡ 脚本语法关键规则（新增） **在编写任何脚本前，必须查看：** `references/script_syntax_critical.md` 这个文档包含了实际脚本编写中最容易出错的语法问题： - ❌ 使用 `cout` 输出 → ✅ 使用 `print()` 函数 - ❌ `on_initialize` 中使用 `script` 包裹 → ✅ 直接写代码 - ❌ 天线方向图直接定义参数 → ✅ 使用 `constant_pattern` 子块 - ❌ 脉冲宽度用 `microsec` → ✅ 使用科学计数法 `1.0e-6 sec` - ❌ 使用三元运算符、fmod、类型转换 → ✅ 使用 if-else 和时间差比较 - ❌ WSF_AIR_MOVER 使用 climb_rate → ✅ 只使用支持的参数 ### Rule 1: File Extension ``` ✅ CORRECT: my_script.txt ❌ WRONG: my_script.wsf ``` **AFSIM scripts MUST use `.txt` extension, NOT `.wsf`** ### Rule 2: Units Required ``` ✅ CORRECT: speed 100 m/sec ❌ WRONG: speed 100 ✅ CORRECT: altitude 5000 ft ❌ WRONG: altitude 5000 ✅ CORRECT: update_interval 1.0 sec ❌ WRONG: update_interval 1.0 ``` **ALL numeric parameters MUST include units** ### Rule 3: End Tags Required ``` ✅ CORRECT: mover WSF_AIR_MOVER maximum_speed 500 m/sec end_mover ❌ WRONG: mover WSF_AIR_MOVER maximum_speed 500 m/sec # Missing end_mover! ``` **Every block MUST have its corresponding `end_*` tag** ### Rule 4: Coordinate Format ``` ✅ CORRECT: position 38:44:52.3n 90:21:36.4w ❌ WRONG: position 38.44.52.3n 90.21.36.4w ``` **Use colon `:` to separate degrees:minutes:seconds** ### Rule 5: Script API Methods ``` ✅ CORRECT: PLATFORM.Name() ✅ CORRECT: PLATFORM.Latitude() ✅ CORRECT: PLATFORM.Altitude() ❌ WRONG: Position() # Does not exist ❌ WRONG: Geodetic() # Does not exist ❌ WRONG: Time() # Use TIME_NOW instead ``` **Only use documented API methods from script_api_reference.md** **For complete error list:** See `references/common_mistakes.md` and `references/script_syntax_critical.md` --- ## ⚙️ Configuration ### config.txt - AFSIM Installation Directory **Location:** `config.txt` in skill root directory The skill uses a configuration file to locate your AFSIM installation. This makes it portable across different computers. **Configuration File:** ``` # AFSIM Installation Directory AFSIM_INSTALL_DIR=D:\Program Files\afsim2.9.0 ``` **Derived Paths:** - **mission.exe**: `{AFSIM_INSTALL_DIR}/bin/mission.exe` - **Documentation**: `{AFSIM_INSTALL_DIR}/documentation/html/docs` **To use on a different computer:** 1. Open `config.txt` 2. Update `AFSIM_INSTALL_DIR` to your AFSIM installation path 3. Save the file All paths (mission.exe, documentation) are automatically derived from this setting. ### Documentation Directory - Ultimate Reference **Location:** `{AFSIM_INSTALL_DIR}/documentation/html/docs` The AFSIM documentation directory contains **1602 HTML files** with complete, authoritative information about every AFSIM feature. **When to use:** - ✅ Need to confirm very specific details - ✅ Looking for obscure parameters or options - ✅ Want to see official examples - ✅ Need to verify edge cases **When NOT to use:** - ❌ For common tasks (use skill references instead) - ❌ For quick lookups (use SKILL.md navigation) - ❌ For examples (use examples.md) **Think of it as:** The ultimate fallback reference when skill documentation doesn't cover a specific detail. --- ## 🚀 Quick Start Guide ### Step 1: Understand Requirements Ask the user about: - **Scenario type**: Air-to-air, air-to-ground, ISR, naval, etc. - **Platforms**: Aircraft, ships, ground vehicles, satellites - **Sensors**: Radar, ESM, EO/IR, etc. - **Weapons**: Missiles, bombs, guns - **Mission timeline**: Duration, key events - **Output needs**: Event logs, tracks, engagement results ### Step 2: Generate Script 1. **Start with file structure** (see [File Structure Reference](#-file-structure-reference)) 2. **Define platform types** with movers (see [Mover Types](#-mover-types-reference)) 3. **Add sensors/weapons** (see [Commands Reference](#-commands-reference)) 4. **Create platform instances** with routes 5. **Add processors** for behaviors (see [Script API](#-script-api-reference)) 6. **Set simulation end time** ### Step 3: Execute Script ```bash python scripts/run_mission.py <script_file.txt> [options] ``` Options: - `-es` - Event-stepped (default) - `-rt` - Real-time frame-stepped - `-fs` - Non-realtime frame-stepped - `-fio` - Flush output - `-sm` - Suppress messages ### Step 4: Validate and Iterate - Check mission.exe output for errors - Verify simulation results - Adjust script and re-run as needed --- ## 📁 File Structure Reference **Location:** `references/file_structure.md` Standard AFSIM script structure: ``` # Header comments script_interface debug end_script_interface # Output configuration event_output file output/simulation.evt enable all end_event_output # Reusable definitions antenna_pattern [name] [...] sensor [name] [type] [...] weapon [name] [type] [...] # Platform types platform_type [name] WSF_PLATFORM mover [type] [parameters] end_mover sensor [name] [type] [parameters] end_sensor processor [name] [type] [parameters] end_processor end_platform_type # Platform instances platform [instance-name] [type] side [blue|red|white] route position [lat] [lon] altitude [alt] speed [speed] end_route end_platform # Simulation control end_time [duration] sec ``` **For complete structure guide:** Read `references/file_structure.md` --- ## 🚁 Mover Types Reference **Location:** `references/mover_reference.md` AFSIM supports 22+ mover types for different platform categories: ### Air Movers - **WSF_AIR_MOVER** - Standard fixed-wing aircraft - **WSF_HELO_MOVER** - Helicopters and rotorcraft - **WSF_GUIDED_MOVER** - Guided missiles and munitions ### Ground Movers - **WSF_GROUND_MOVER** - Ground vehicles - **WSF_RAIL_MOVER** - Rail-based systems ### Naval Movers - **WSF_SURFACE_MOVER** - Surface ships - **WSF_SUBSURFACE_MOVER** - Submarines ### Space Movers - **WSF_ORBITAL_MOVER** - Satellites and orbital platforms - **WSF_BALLISTIC_MOVER** - Ballistic missiles ### Special Movers - **WSF_STATIONARY_MOVER** - Fixed installations - **WSF_SCRIPTED_MOVER** - Custom movement logic **Example:** ``` mover WSF_AIR_MOVER maximum_speed 500 m/sec minimum_speed 100 m/sec default_radial_acceleration 5.0 g default_climb_rate 50 m/sec end_mover ``` **For complete mover reference:** Read `references/mover_reference.md` --- ## 🔧 Script API Reference **Location:** `references/script_api_reference.md` ### Core Classes #### WsfPlatform Platform access and control: ``` string Name() # Get platform name string Type() # Get platform type double Latitude() # Get latitude (deg) double Longitude() # Get longitude (deg) double Altitude() # Get altitude (m) double X(), Y(), Z() # Get XYZ position (m) double Heading() # Get heading (deg) double Speed() # Get speed (m/s) WsfSensor Sensor(string name) # Get sensor by name WsfWeapon Weapon(string name) # Get weapon by name WsfProcessor Processor(string) # Get processor by name int SensorCount() # Number of sensors WsfSensor SensorEntry(int i) # Get sensor by index ``` #### WsfSensor Sensor access and control: ``` string Name() # Get sensor name string Type() # Get sensor type bool IsTurnedOn() # Check if sensor is on void TurnOn() # Turn sensor on void TurnOff() # Turn sensor off ``` #### WsfWeapon Weapon access and control: ``` string Name() # Get weapon name string Type() # Get weapon type int QuantityRemaining() # Get remaining quantity bool Fire(WsfTrack target) # Fire at target ``` #### WsfTrack Track information: ``` WsfTrackId TrackId() # Get track ID string TargetName() # Get target name double Latitude() # Get track latitude double Longitude() # Get track longitude double Altitude() # Get track altitude double Range() # Get range to track bool LocationValid() # Check if location valid ``` #### Array<T> and Map<K,V> Collections: ``` # Array methods void PushBack(T value) # Add element T Get(int index) # Get element int Size() # Get size ArrayIterator GetIterator() # Get iterator # Map methods void Insert(K key, V value) # Insert key-value pair V Get(K key) # Get value by key bool Contains(K key) # Check if key exists int Size() # Get size ``` ### Global Variables ``` PLATFORM # Current platform PROCESSOR # Current processor SENSOR # Current sensor TRACK # Current track MESSAGE # Current message TIME_NOW # Current simulation time ``` **For complete API reference:** Read `references/script_api_reference.md` --- ## 📋 Commands Reference **Location:** `references/commands_reference.md` ### Platform Commands ``` platform [name] [type] side [blue|red|white|...] position [lat] [lon] altitude [alt] command_chain [name] [commander|SELF] route position [lat] [lon] altitude [alt] speed [speed] end_route sensor [name] on # or off end_sensor weapon [name] quantity [number] firing_interval [time] sec end_weapon end_platform ``` ### Route Commands ``` route position [lat] [lon] altitude [alt] speed [speed] position [lat] [lon] altitude [alt] agl speed [speed] position [lat] [lon] # Uses previous altitude/speed end_route ``` ### Sensor Commands ``` sensor [name] [type] frame_time [time] sec location [x] [y] [z] minimum_range [range] nm maximum_range [range] nm processor [processor-name] end_sensor ``` ### Weapon Commands ``` weapon [name] [type] launched_platform_type [type] weapon_effects [effects-name] category [category-name] end_weapon ``` ### Processor Commands ``` processor [name] [type] update_interval [time] sec script_variables [type] [name] = [value]; end_script_variables script [return-type] [name]([parameters]) # Script code end_script on_initialize # Initialization code end_on_initialize on_update # Update code end_on_update end_processor ``` **For complete commands reference:** Read `references/commands_reference.md` --- ## 📨 Message Types Reference **Location:** `references/message_types_reference.md` AFSIM消息系统用于平台、传感器、处理器之间的通信。 ### 核心消息类型 #### WsfMessage (基类) 所有消息的基类： ```javascript string Originator() // 消息发起平台 string Type() // 消息类型 int Priority() // 消息优先级 void SetAuxData(string name, value) // 设置辅助数据 ``` #### WsfTrackMessage 传递轨迹信息： ```javascript WsfTrack Track() // 获取轨迹 void SetTrack(WsfTrack aTrack) // 设置轨迹 ``` #### WsfControlMessage 发送控制命令： ```javascript