APX orchestrator

Stop debugging, start racing.

User Tools

Site Tools


hooks

Reciever hooks

APX offers the possibility to add an event-driven API to the rFactor 2 server, allowing you to react effective on race situations.

Add a new hook

Make sure that the hook execution stays below 1 second. Otherwise use threads and locks.

Hooks won't work properly if running in debug mode.

Hooks consist out of a Python file inside of /hooks/ and a method to be called. To reigster the hook, the method needs to be included in init file in the /hooks/ directory.

Also, the hook needs to be registered using /register(“eventName”, HOOKS, method)/. The eventName is case sensitive.

An example for the contents of /hooks/ is available here: https://github.com/apx-simracing/hooks. Take a look especially on https://github.com/apx-simracing/hooks/blob/main/__init__.py to see how the order of hooks is controlled.

The hooks getting executed per event based on their register order.

Hook list

onCarCountChange (vehicles: list, vehicles: list)

Fires if the amount of cars Change. If a car can resumes a race, the event won't be fired.

onDriverPenaltyChange(driver: str, old_penalty_count: int, new_penalty_count: int)

Fires if the amount of penalties for a driver changes.

onFinishStatusChange(driver: str, old_status: str, new_status: str)

Will be executed if the finish state changes. old_status and new_status can have following string-based values:

  • FSTAT_NONE
  • FSTAT_DNF
  • FSTAT_DQ

if a entry is new, this event will be fired.

onLowSpeed(driver: str, speed: float, location: float, nearby_drivers: list, team_name: str)

The file with “init” in the hooks directory contains the constant LOW_SPEED_THRESHOLD to control the comparison value for this hook.

This event will be called as often until the car resumes racing speed or gets back to pit or garage.

Will be executed if a driver is not in garage or pitting and the car velocity is below 50 km/h. The location parameter will contain the current track position.

nearby_drivers is a list of driver names nearby

onPitStateChange(driver: str, old_status: str, new_status: str)

Will be executed if the pit state changes. old_status and new_status can have following string-based values:

  • NONE
  • REQUEST
  • ENTERING
  • STOPPED
  • EXITING

if a entry is new, this event will be fired.

onSessionChange(old_session: str, new_session: str)

Will be called when a server session switches. Example values for old_session and new_session:

  • PRACTICE1
  • QUALIFY1
  • RACE1
  • INVALID

During startup and certain switch transistions, the server will switch to INVALID first.

onShownFlagChange(driver: str, old_yellow_flag: bool, new_yellow_flag: bool)

If the shown yellow flag for a driver changes, the event will be called.

onStart()

Called after server is started.

As the start is asynchronous, the process may not be listening when the event is fired.

onStop()

Called after server is stopped.

onDriverSwap (slotId: int, oldDriver: str, newDriver: str)

Fires if an driver switches. The slotId is the rFactor 2 slot id, which is basically a zero-based index.

onNewResult(oldResults: list, newResults:list)

The hook fires if the file is existing, but maybe not until it's free of handle blocks.

Fires if a new result file gets written. Both arrays contain filenames only.

onNewReplay(oldReplays: list, oldReplays:list)

The hook fires if the file is existing, but maybe not until it's free of handle blocks.

Fires if a new replay file gets written. Both arrays contain filenames only.

onNewBestLapTime(driver, best_lap, teamName)

The hook may fire at the start of an event multiple times. Use a delay. If the reciever restarts, the same behaviour will occur.

Fires if a new best lap was done.

hooks.txt · Last modified: 2021/03/28 17:22 by chmr