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 - READ FIRST - Common mistakes that cause failures
• Quick Start Guide - Get started in 4 steps

📖 Core References

• File Structure - Standard AFSIM script structure
• Mover Types - All 22+ mover types with parameters
• Script API - WsfPlatform, WsfSensor, WsfWeapon classes
• Commands - Platform, route, sensor, weapon commands
• Message Types - WsfMessage system and all message types
• Sensor Types - Radar, ESM, EO/IR sensor parameters
• Examples - Complete working examples

🔧 Advanced Topics

• Script Execution - Running scripts with mission.exe
• 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)
2. Define platform types with movers (see Mover Types)
3. Add sensors/weapons (see Commands Reference)
4. Create platform instances with routes
5. Add processors for behaviors (see Script API)
6. Set simulation end time

Step 3: Execute Script

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 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 (基类)

所有消息的基类：

string Originator()                      // 消息发起平台
string Type()                            // 消息类型
int Priority()                           // 消息优先级
void SetAuxData(string name, value)      // 设置辅助数据

WsfTrackMessage

传递轨迹信息：

WsfTrack Track()                         // 获取轨迹
void SetTrack(WsfTrack aTrack)           // 设置轨迹

WsfControlMessage

发送控制命令：

void SetFunction(string aFunction)       // 设置功能
void SetResource(string aResource)       // 设置资源
void SetTrack(WsfTrack aTrack)           // 设置关联轨迹

WsfStatusMessage

报告状态：

void SetStatus(string aStatus)           // 设置状态
void SetSystemName(string aSystemName)   // 设置系统名称

WsfBMTrackMessage

战场管理轨迹（功能最丰富）：

void SetLLA(double lat, double lon, double alt)  // 设置位置
void SetIFFFriendly()                    // 设置IFF为友方
void SetTrackingStatusNormal()           // 设置跟踪状态

消息处理示例

on_message
   type WSF_TRACK_MESSAGE
      script
         WsfTrackMessage msg = (WsfTrackMessage)MESSAGE;
         WsfTrack track = msg.Track();
         // 处理轨迹消息
      end_script

   type WSF_CONTROL_MESSAGE
      script
         WsfControlMessage msg = (WsfControlMessage)MESSAGE;
         // 处理控制消息
      end_script
end_on_message

For complete message types reference: Read references/message_types_reference.md

📡 Sensor Types Reference

Location: references/sensor_types_reference.md

AFSIM提供多种特殊传感器类型，每种都有特定的参数和配置。

WSF_RADAR_SENSOR - 雷达传感器

主动雷达探测传感器：

关键参数：

transmitter
   frequency <frequency>                 // 工作频率
   power <power>                         // 发射功率
   pulse_width <time>                    // 脉冲宽度
   pulse_repetition_frequency <freq>     // PRF
   antenna_pattern <pattern-name>        // 天线方向图
end_transmitter

receiver
   noise_figure <db-ratio>               // 噪声系数
   bandwidth <frequency>                 // 接收带宽
end_receiver

swerling_case [0|1|2|3|4]                // Swerling目标模型
number_of_pulses_integrated <integer>    // 积分脉冲数
one_m2_detect_range <length>             // 1平方米目标检测距离

WSF_ESM_SENSOR - ESM传感器

被动RF检测传感器（RWR、SIGINT、ELINT）：

关键参数：

frequency_band <lower-freq> <upper-freq>
   dwell_time <time>                     // 驻留时间
   revisit_time <time>                   // 重访时间

continuous_detection_sensitivity <db-power>  // 连续波灵敏度
pulsed_detection_sensitivity <db-power>      // 脉冲灵敏度
detection_threshold <db-ratio>           // 信噪比门限
scan_on_scan_model <boolean>             // 扫描-扫描模型
ranging_time <time>                      // 测距时间

WSF_EOIR_SENSOR - 光电/红外传感器

光学或红外成像传感器：

关键参数：

pixel_count <horizontal> <vertical>      // 像素数量
band [visual|short|medium|long|very_long]  // 波段选择
atmospheric_attenuation <value> per <length>  // 大气衰减
background_radiance <value> <units>      // 背景辐射
detection_threshold <value>              // 信噪比门限
noise_equivalent_irradiance <value> <units>  // NEI

传感器类型对比

For complete sensor types reference: Read references/sensor_types_reference.md

📝 Examples Reference

Location: references/examples.md

Example 1: Basic Air Platform

Simple aircraft with route and script processor

Example 2: Strike Mission

Complete scenario with sensors, weapons, track sharing, and engagement logic

Example 3: Ground Patrol

Ground vehicle with patrol route

Example 4: Naval Platform

Surface ship with radar sensor

Common Patterns

• Script variables declaration
• Looping through collections
• Conditional logic
• Message handling
• Accessing platform components

For complete examples: Read references/examples.md

⚙️ Script Execution

Configuration

The skill reads AFSIM installation directory from config.txt:

AFSIM_INSTALL_DIR=D:\Program Files\afsim2.9.0

All paths are derived from this:

• mission.exe: {AFSIM_INSTALL_DIR}/bin/mission.exe
• Documentation: {AFSIM_INSTALL_DIR}/documentation/html/docs

Using run_mission.py

# Basic execution
python scripts/run_mission.py my_script.txt

# With options
python scripts/run_mission.py my_script.txt -es -fio

# Real-time mode
python scripts/run_mission.py my_script.txt -rt

The script will:

1. Load configuration from config.txt
2. Verify mission.exe exists
3. Display configuration paths
4. Execute the script
5. Capture and display output

Execution Modes

• Event-stepped (-es): Default, fastest execution
• Real-time (-rt): Runs in real-time with frame stepping
• Frame-stepped (-fs): Non-realtime frame stepping

Output Files

Scripts generate output in the output/ directory:

• .evt - Event log files
• .rep - Binary replay files
• Console output from mission.exe

Troubleshooting Configuration

Problem: mission.exe not found

• Solution:
  1. Open config.txt
  2. Verify AFSIM_INSTALL_DIR points to your AFSIM installation
  3. Check that {AFSIM_INSTALL_DIR}/bin/mission.exe exists

Problem: Different computer, different path

• Solution:
  1. Copy the entire skill directory
  2. Update AFSIM_INSTALL_DIR in config.txt
  3. Everything else works automatically

🔍 Troubleshooting

Syntax Errors

Problem: "Unexpected token" or "Parse error"

• Solution: Check references/common_mistakes.md for common syntax errors
• Verify all blocks have end_* tags
• Check coordinate format (use : not .)
• Ensure all numbers have units

Problem: "Unknown command"

• Solution: Verify command syntax in references/commands_reference.md
• Check spelling and capitalization
• Ensure command is in correct context

Execution Errors

Problem: mission.exe not found

• Solution: Verify path is D:\Program Files\afsim2.9.0\bin\mission.exe
• Check file permissions
• Ensure AFSIM 2.9.0 is installed

Problem: Script file not found

• Solution: Use .txt extension, not .wsf
• Check file path is correct
• Ensure file exists in specified location

Runtime Errors

Problem: Platform not moving

• Solution: Check mover parameters in references/mover_reference.md
• Verify route has valid waypoints
• Ensure speed is specified with units

Problem: Sensor not detecting

• Solution: Verify sensor is turned on
• Check sensor range and parameters
• Ensure target is within sensor coverage

Problem: Script variables not working

• Solution: Declare variables in script_variables block
• Check variable types match usage
• Verify semicolons after declarations

📚 Complete Reference Library

All reference files are located in the references/ directory:

1. script_syntax_critical.md - ⭐ NEW: 脚本编写关键语法规则速查（必读）
2. common_mistakes.md - 10 critical rules to avoid common errors
3. file_structure.md - Standard AFSIM script file structure and templates
4. mover_reference.md - Complete reference for all 22+ mover types
5. script_api_reference.md - Full API for WsfPlatform, WsfSensor, WsfWeapon, etc. (158 methods)
6. commands_reference.md - Complete command syntax reference
7. message_types_reference.md - WsfMessage system and all message types
8. sensor_types_reference.md - Radar, ESM, EO/IR sensor parameters
9. examples.md - Working examples and common patterns

Load these files as needed for detailed information.

🎯 Best Practices

1. Always start with file_structure.md to understand the standard layout
2. Check common_mistakes.md before generating any script
3. Use examples.md as templates for common scenarios
4. Verify mover types in mover_reference.md before defining platforms
5. Reference script_api_reference.md when writing processor scripts
6. Test incrementally - start simple, add complexity gradually
7. Use meaningful names for platforms, sensors, weapons
8. Add comments to explain complex logic
9. Validate coordinates - use proper lat/lon format
10. Check units - every number needs units

📞 Support

Configuration

• Config File: config.txt in skill root directory
• Default Install: D:\Program Files\afsim2.9.0
• Update for your system: Edit AFSIM_INSTALL_DIR in config.txt

AFSIM Resources

• Installation: Configured via config.txt
• Documentation: {AFSIM_INSTALL_DIR}/documentation/html/docs (1602 HTML files)
• Mission.exe: {AFSIM_INSTALL_DIR}/bin/mission.exe
• Version: AFSIM 2.9.0

Documentation Hierarchy

1. SKILL.md - Quick reference and navigation (use first)
2. references/ - Comprehensive skill documentation (use for details)
3. {AFSIM_INSTALL_DIR}/documentation/ - Ultimate official reference (use for edge cases)

🔄 Workflow Summary

1. Understand Requirements
   ↓
2. Check common_mistakes.md
   ↓
3. Use file_structure.md as template
   ↓
4. Add platform types (mover_reference.md)
   ↓
5. Add sensors/weapons (commands_reference.md)
   ↓
6. Add behaviors (script_api_reference.md)
   ↓
7. Create platform instances
   ↓
8. Save as .txt file
   ↓
9. Execute with run_mission.py
   ↓
10. Validate output and iterate

Remember: File extension MUST be .txt and ALL numbers MUST have units!