Skip to main content

​
Overview

Hooks allow your plugin to intercept and modify network packets between the client and server. Each hook corresponds to a specific YSFlight network command and can be registered for both client-to-server and server-to-client traffic.

​
Registering Hooks

Use the register_hook() method to register a hook in your plugin’s register() method: 
def register(self, plugin_manager):
    self.plugin_manager = plugin_manager
    self.plugin_manager.register_hook('on_flight_data', self.on_flight_data_handler)

​
Method Signature

​
plugin_manager.register_hook
function
Registers a hook callback with the plugin manager.Parameters:
  • hook_name (str): Name of the hook to register
  • callback (function): Function to call when the hook is triggered

​
Hook Callback Signature

All hook callbacks must follow this signature: 
def hook_callback(self, data, player, message_to_client, message_to_server):
    # Your hook logic here
    return True  # or False
​
data
bytes
Raw packet data for this network command
​
player
Player
The player object associated with this packet. Contains:
  • player.aircraft.id - Aircraft ID
  • player.iff - IFF (Identify Friend or Foe) value
  • player.aircraft.last_packet - Last received flight data packet
  • player.streamWriterObject - Stream writer for sending data to player
​
message_to_client
list
List to append packets that should be sent to the client. Add encoded packets here to send additional data.
​
message_to_server
list
List to append packets that should be sent to the server. Add encoded packets here to forward modified data.

​
Return Value

Your hook callback must return a boolean:
  • True - Forward the original packet to its destination
  • False - Block the original packet (useful when you modify and resend it)
If your callback doesn’t return a boolean value, a warning will be logged.

​
Available Hooks

​
Client to Server Hooks

These hooks intercept packets sent from the client to the server:
Triggered when a player logs in.Hook name: on_loginPacket type: FSNETCMD_LOGON
Triggered when a player logs out.Hook name: on_logoutPacket type: FSNETCMD_LOGOFF
Triggered when a player requests to join the game.Hook name: on_join_requestPacket type: FSNETCMD_JOINREQUESTExample use cases:
  • Validate player aircraft
  • Enforce server rules
  • Log join attempts
Triggered continuously when the client sends flight data updates.Hook name: on_flight_dataPacket type: FSNETCMD_AIRPLANESTATEExample use cases:
  • Track player positions
  • Monitor G-forces
  • Implement flight restrictions
Note: This is a high-frequency hook. Keep processing lightweight.
Triggered when a player sends a chat message.Hook name: on_chatPacket type: FSNETCMD_TEXTMESSAGEExample use cases:
  • Filter profanity
  • Modify messages
  • Log chat activity
Triggered when a player leaves the aircraft.Hook name: on_unjoinPacket type: FSNETCMD_UNJOIN
Triggered when a player receives damage.Hook name: on_get_damagePacket type: FSNETCMD_GETDAMAGE
Triggered when a player launches a missile.Hook name: on_missile_launchPacket type: FSNETCMD_MISSILELAUNCH
Triggered when weapon configuration changes.Hook name: on_weapon_configPacket type: FSNETCMD_WEAPONCONFIG
Triggered for air commands.Hook name: on_air_cmdPacket type: FSNETCMD_AIRCMD
Triggered when a player locks onto a target.Hook name: on_lockonPacket type: FSNETCMD_LOCKON
Triggered when smoke color is changed.Hook name: on_smoke_colorPacket type: FSNETCMD_SMOKECOLOR
Additional client-to-server hooks:
  • on_error - Error packets
  • on_load_field - Field loading
  • on_add_object - Object addition
  • on_readback - Readback packets
  • on_join_approval - Join approval
  • on_reject_join_request - Join rejection
  • on_remove_airplane - Airplane removal
  • on_request_test_airplane - Test airplane request
  • on_kill_server - Server kill request
  • on_prepare_simulation - Simulation preparation
  • on_test_packet - Test packets
  • on_remove_ground - Ground object removal
  • on_environment - Environment settings
  • on_sky_color - Sky color changes
  • on_fog_color - Fog color changes
  • on_list - List requests

​
Server to Client Hooks

These hooks intercept packets sent from the server to the client. Add _server suffix to any client hook name: 
# Server to client version of on_flight_data
plugin_manager.register_hook('on_flight_data_server', self.on_flight_data_from_server)
Available server hooks:
  • on_login_server
  • on_logout_server
  • on_join_request_server
  • on_flight_data_server
  • on_chat_server
  • on_unjoin_server
  • on_get_damage_server
  • And all other hooks with _server suffix
Server hooks are useful for modifying data before it reaches the client, such as implementing radar systems that hide enemy positions.

​
Common Patterns

​
Modifying Packets

To modify a packet, decode it, modify the data, encode a new packet, and return False: 
def on_chat(self, data, player, message_to_client, message_to_server):
    decode = FSNETCMD_TEXTMESSAGE(data)
    modified_message = decode.raw_message.upper()
    
    new_packet = FSNETCMD_TEXTMESSAGE.encode(modified_message, with_size=True)
    message_to_server.append(new_packet)
    
    return False  # Block original packet

​
Sending Additional Packets

To send additional packets without blocking the original: 
def on_flight_data(self, data, player, message_to_client, message_to_server):
    if player.aircraft.last_packet.g_value > 10:
        warning = FSNETCMD_TEXTMESSAGE.encode("Warning: High G-force!", True)
        message_to_client.append(warning)
    
    return True  # Forward original packet

​
Blocking Packets

To silently drop a packet without replacement: 
def on_chat(self, data, player, message_to_client, message_to_server):
    decode = FSNETCMD_TEXTMESSAGE(data)
    
    if "spam" in decode.raw_message.lower():
        return False  # Block spam messages
    
    return True

Build docs developers (and LLMs) love

Get started for freeTalk to us