Extending the API

General

This is directed at changes included in Spearmint, not compatibility with engine forks that change the APIs.

Common

system calls

VM to engine calls.

New syscalls

After VM APIs reach major version 1, new syscalls will be able to be added without breaking compatibility. By increasing minor version when added, older engine will be aware of compatibility issue.

Currently VMs using newer API than engine supports will not be loaded. FIXME: Let VM support multiple minor versions?

New arguments for syscalls

It will be possible to add additional arguments at end of list without breaking compatibility. Using the API version the engine will know whether argument exists, if not can use a default value for the argument.

Using the newer API version will require passing the additional arguments. The VM chooses what the max API version is. When updating [cg|g]_public.h / tr_types.h, the [cg|g]_syscalls.[c|h] files will have to be updated too.

There will probably be done using a macro like VM_MINVER( minimum-major-version, minimum-minor-version, data, default ), VM_ARG( 1, 2, args[5], 0 ). FIXME: Add support for this.

VM calls

Engine to VM calls.

FIXME: How does engine know if VM supports a call? More version magic?

entity state / player state

The engine cannot extend it's sharedEntityState_t and sharedPlayerState_t which could be a problem in the future. FIXME: tell engine what size they are so it knows if supports 'new' fields?

VMs are able to extend entityState_t and playerState_t as it wants.

The VM is able to specify expected sum of all the netfields for entityState_t and playerState_t. Allows CGame to support old demos with less netfields (by adding code that handles different CS_GAME_VERSION values) without dropping the error checking (e.g., someone added a field to entityState_t and forgot to add it to netfields).

CGame

The following structure can have new fields added to the end without breaking the API.

• uiClientState_t
• gameState_t
• glconfig_t
• vmSnapshot_t
• refdef_t
• refEntity_t
• fontInfo_t

The following were decided not worth extending, and cannot be without adding new syscalls.

• polyVert_t
• polyBuffer_t