The VScript-Python Interface (VPI) is a custom tool originally written by Mince and heavily modified for potato servers. It allows mappers and mission makers to pass VScript data outside of the game engine to a python "server" running on every server region, requiring zero sourcemod/metamod dependencies.

We use this system primarily as a database connector, however it's also used for our MGE VScript server to make API requests to our webserver and track ELO/leaderboard stats on a 100% vanilla TF2 server, and for interfacing with the discord bot for the !seed command. Condemned - Trespasser Remastered and Underworld - Undead Dread also use this system to track your win count and other "achievements".

You need to ask before you can use it

VPI requires custom code implementation on the python side to do anything, and I am not interested in letting anyone run arbitrary non-sandboxed python code on my servers. Get a final or near-final implementation done in VScript FIRST before requesting VPI integration.

If your mission needs to interact with a database, use simple FileToString/StringToFile functions for your implementation, then we can talk about converting it to VPI and writing custom code for it. Look at Trespasser Remastered, notice the commented out code related to StringToFile/FileToString? This mission originally used basic file-based tracking, and can be easily converted back by commenting out the VPI lines instead and uncommenting the StringToFile lines.

If your map/mission does something else with the VPI that is not connecting to a database (e.g. steam API requests), let me know what you intend to do and we'll work something out.

Using the VPI (VScript)

VPI.AsyncCall({ func = string, kwargs = table, callback = function })
This is the VScript function that does all of the heavy lifting, it accepts a table of arguments to pass to python and returns a response.

func is the string name of the python function that will be executed, these function names are whitelisted to only be called from a specific VScript file on a specific map/mission

kwargs is the table of arguments that will be passed to python. Argument names like query_mode for trespasser will be custom for every function and are not a reference for how all VPI calls are structured.

callback is the VScript function that will be executed once the round-trip process of writing JSON -> Python server accepts input -> Python server emits output -> VScript reads the JSON output is completed.

IMPORTANT: the callback format of callback = function(response, error) { ... } is the ONLY format that will work! function callback(response, error) { ... } will SILENTLY FAIL!

As the name implies, this is an asynchronous function. What this means is VPI calls will not instantly give a response, and reading data must be done through a callback function.

Because of the inherently slow and clunky nature of relaying data between two separate scripting VMs through the filesystem, any requests to use VPI for very expensive/dumb things, e.g. tracking every player eye position every tick, will be rejected. Similar to StringToFile/FileToString, you should structure your code around "quiet periods", between waves or on player connect/disconnect events are great examples of when you should run your VPI calls.

Here is the source code from Underworld - Undead Dread with added code comments and slight formatting changes. This doesn't use any callback function, just sends out a DB write request.

// ... snippet from player logging function
// https://github.com/potato-tf/ArchiveAssets/blob/ba0e0c195ee2971bf0f4085d4393a803e5b41070/scripts/vscripts/playerlog_pea.nut#L23

// Check if VPI is actually active
if ("VPI" in getroottable()) {

        // Run our VPI call to write our wave progress
       // The passed argument must be a table, similar to SpawnEntityFromTable or TraceLineEx
	VPI.AsyncCall({

                // tell the python server we want to call this function
		func = "VPI_DB_UndeadDread_ReadWrite",

                // pass these arguments to the python function
		kwargs = {

                        // call the function in write mode
			query_mode = "write",
                        // pass the players steamid 
                        // "lastfetchresults" is part of a larger function, assume this is a steamid string
			network_id = lastfetchresults.steamid,
                        // pass the wave data we want to write to the query
			wave_data = waveprogress
		}
	})
}

Using the VPI (Python)

As mentioned before, the python side of the code needs to be custom implemented by myself or other staff members, however you are free to provide us with code that we can vet and confirm isn't doing anything nefarious. If you'd like to provide your own python code, you don't need to worry about testing and running it yourself, it just needs to follow this structure, we can hammer out any problems later.

If providing custom DB connector code, you must also provide a standalone CREATE TABLE query.

Here is the source code for VPI_DB_UndeadDread_ReadWrite with added code comments:

# This is a wrapper function that handles database connector logic
@WrapDB
# `info` is the entire table passed to VPI.AsyncCall, `cursor` is your database connection.
async def VPI_DB_UndeadDread_ReadWrite(info, cursor):

    # grab the `query_mode` kv from the `kwargs` table we filled out in VScript
    # NOTE: `kwargs` is not an arbitrary name, many parts of the code assume this table name.
    kwargs = info["kwargs"]
    query_mode = kwargs["query_mode"]

    # check if we're reading from the DB or writing to it (also accepts 0/1 instead of "read"/"write")
    if (query_mode == "read" or query_mode == 0):

        # grab the steamid (`network_id`) we passed to kwargs.
        network_id = kwargs["network_id"]
        
        # now run the SQL query to grab wave data for this player.
        # NOTE: The `undead_dread` table is manually created by a staff member
        await cursor.execute("SELECT wave_data FROM undead_dread WHERE steam_id = %s", (network_id,))

   # write the wave data for this steamid instead of reading it.
    elif (query_mode == "write" or query_mode == 1):

        network_id = kwargs["network_id"]
        wave_data = kwargs["wave_data"]

        # MySQL/MariaDB query to either add a new steamid to the `undead_dread` DB table, or update an existing one with new wave data.
        # NOTE: The logic for handling wave data is handled on the VScript side, this query overwrites whatever is already in the wave_data column.
        await cursor.execute("""INSERT INTO undead_dread (steam_id, wave_data)
                             VALUES (%s, %s)
                             ON DUPLICATE KEY UPDATE wave_data = VALUES(wave_data)
                             """, (network_id, wave_data))

    # returns the results of the SQL query and writes the output to JSON.  VScript callback is fired and takes over from here.
    return await cursor.fetchall()

The entire python ecosystem is now your canvas to do horrible things in your missions, go crazy.