Getting started

Limitations

What amxts cannot do yet, each with what to write instead. The build, the editor or the server console says so for almost every item below; this page is where to look up what it means.

How a feature behaves because of the game, AMX Mod X, the protocol or a file format - a timer fires on a server frame, a chat message has one team colour - is noted on that feature's own page, beside what it concerns.

The language

A plugin is TypeScript compiled to WebAssembly and then to machine code. What TypeScript has and a plugin does not:

  • throw takes an Error or a string, which becomes an Error with it as the message: throw 42 does not build. A catch gets an Error - error.message, error.name, instanceof for a class of your own. A crash that is not an error - a stack overflow - ends the call past every catch.
  • In tests an error's stack is its first line: the fake server (amxts test) runs a plugin without the frames a game server keeps. Check error.message; the calls show on a server (errors).
  • A union of text, numbers and booleans is read with as.string | number, string | number | boolean | null hold any of them, and print, compare and go to JSON as what they hold; typeof says which. Where TypeScript narrows after typeof value == "number", the build does not: write value as number there. A value read as one type without as does not build, and the message says so. Such a union may hold a Uint8Array too, as a query's values do (DatabaseValue): typeof says "object" of it, and value as Uint8Array takes it out.
  • No other unions of different types. A union of classes, and cond ? 1 : "a" with no type declared for it, do not build. Unions of string literals ("CT" | "TERRORIST"), T | null and T | undefined work, and so do true | false | "default", one or a list (T | T[]) and a function-or-list option such as menu-core's enabled. Use two parameters, two functions, or a common base class.
  • A type alias does not reach itself. type Text = string | ((context: Context) => string) does not build ("Recursive types") when Context has a field of a class with a field of type Text. Write the type out at that field: title: string | ((context: Context) => string).
  • No any and unknown. Every value has a type when the plugin is built.
  • An object literal takes its type from its values, so each value needs one: { owner: null } or { items: [] } alone does not build - declare an interface (const team: Team = { ... }), or write the literal where the type is known.
  • An empty array says its type: const rows = [] does not build, though TypeScript reads the type off the later push. Write it - const rows: Row[] = [] - or build the array with map and filter; amxts typecheck points at such a line.
  • A plain object goes where another is expected when it has the same fields: { y: 2, x: 1 } is a Point of x and y, and a label given goes where label? is optional; one that leaves an optional field out does not - write the literal where the type is known.
  • An object literal's methods have no this of the object: where an interface has methods, a literal of it writes them as arrows or as run() { ... }, and reads the object's fields through a variable.
  • A class goes where an interface of fields is expected when it says implements, and extends no other class: class Spot implements Point is a Point; a class of the same fields without implements is not.
  • JSON.parse is told what it reads: JSON.parse<Settings>(text), or JSON.parse(text) as Settings; alone it does not build. A field the text leaves out that is neither optional nor has a default is a TypeError, where JavaScript leaves it undefined. JSON.stringify takes no replacer function (JSON).
  • Regular expressions have no lookbehind ((?<=...)), named groups, \p{...} or the u and d flags: such a pattern is a SyntaxError. A group that did not match reads as "", not undefined; a function given to replace gets the match and up to four groups. A match that takes more than five million steps throws an Error, so that a pattern that backtracks without end does not hold the server.
  • A date knows a few languages and no Intl: toLocaleString and the rest take a language (en-US, en-GB, de, fr, ru), not options, and toString writes the time zone as its offset, without its name in brackets (time).
  • A typed array is made by its length: new Uint8Array([1, 2, 3]) and Uint8Array.from(list) do not build. Write new Uint8Array(3) and set its elements, or take the bytes fs.readBytesSync and fetch give.
  • A typed array's element written as a value is what the array stored: in a Uint8Array, ++bytes[i] of 255 and (bytes[i] = 300) give 0 and 44, where JavaScript gives 256 and 300; and a Uint8ClampedArray drops a fraction (1.5 is stored as 1) where JavaScript rounds it to the nearest even (2). Read the element as a number before writing it: const next = bytes[i] + 1; bytes[i] = next;.
  • A 32-bit integer adds and multiplies in 32 bits: a string's length, charCodeAt and indexOf, an array's length, an Int32Array's element - text.length * 1_000_000_000 past 2^31 wraps around, where JavaScript gives the exact number. Keep it in a number first: const length: number = text.length.
  • Syntax that does not build:
    Does not buildWrite instead
    function*, yieldan array, or async functions and await
  • A class field holding an arrow that returns more than a plain value needs its type: onTick = () => { ... } and double = (n: number) => n * 2 build; label = () => this.makeLabel() needs label: () => string = () => this.makeLabel().

Variables and optional values

  • A method that runs early through a base class may read a variable before its declaration as an empty value, where JavaScript throws a ReferenceError.
  • Inside a closure, a boolean left out is false: a flag?: boolean parameter, or a variable that holds an optional boolean field, read in an arrow function made inside the function does not see it was left out - () => flag ?? true is false. Read it outside: const loud = flag ?? true.
  • undefined is known by the type written where it is read: an optional field or parameter, a variable or a function's result of T | undefined, find and map.get - and a variable that holds one of them - print as undefined and count as NaN. An item read by index from an array of T | undefined prints text as null, and a number counted with stays undefined: give it a default with ?? first.
  • x! on a null throws a TypeError right there, where TypeScript's ! does nothing and JavaScript throws only where the value is used.
  • boolean | null is a field or a variable, not a parameter or a return type: a call passes the boolean alone, so its null would be lost, and the build says so. Pass the object that holds it, or use number | null. typeof of a number | null that is null is "number".

Async and promises

  • Async generators (async function*) do not build.
  • Promise.race and any need one type: promises of a number and a string, or a number and a sleep, do not build. Await them one by one.
  • Promise.all of different types takes up to 8 promises; promises of one type, or a list, have no such limit (async).
  • A waiting async function keeps up to 4 KB of its own state; one that needs more is stopped, with a message in the console.

Events, forwards and natives

  • A command's handler is written in the call: the object it gets - player and the arguments - is a type the build makes for that call. It goes where the interface of its arguments goes, (args) => kick(args) for kick(args: KickArgs); without one it has no name to give a function written apart: take its parts there, ({ player, text }) => say(player, text). A function declared at the top level of the file is given by its name to a command added there, server.addCommand<KickArgs>("/kick <target>", kick), and gets the interface without player. A command without arguments takes a function of the player, checkpoint(player: Player), wherever it is written. A command's arguments are written in its usage - in place, or after a name made at run time, `${name} [value]`; a usage held in a variable takes none.
  • An event name is written out: server.addEventListener(name, ...) or server.addMessageListener(name, ...) with the name in a variable does not build - the name picks the event's type - and neither does a loop over names (for (const name of ["statusText", "statusValue"] as const)): write a call for each name. amxts typecheck points at such a call. So is a "playerChange" listener's field: { field: "spawnProtected" }, not a variable. Without field, the event's value has no type: read the field from event.player.
  • A game listener either always answers or never does. One that should answer only sometimes returns nothing and calls event.preventDefault(), or always answers, repeating the game's rule for the rest (game events).
  • A vector field of a game event is written whole:event.direction = new Vector(x, y, z); event.direction.x = 1 changes a copy (game events).
  • A Team or a RoundWinner argument of a forward needs the forward declared in an include (forwards).
  • A forward a Pawn plugin makes in plugin_natives does not reach TypeScript; one made from plugin_precache on does - make it in plugin_init, as Pawn plugins usually do.
  • A forward's subscriber neither answers the forward nor changes its arguments: it hears a Pawn plugin's or a module's forward after the Pawn handlers, with a by-reference argument and a text buffer as they left them, and the forward answers what the Pawn handlers answered. A handler that answers or changes them is a Pawn plugin's public (forwards).
  • A number in a native's any:... tail is a Float: only where amxts knows the native reads one - engfunc, dllfunc, ExecuteHam, pev and the others natives lists; elsewhere it goes as a whole number. Where such a native also writes text, read that and convert it: nvault_get(vault, key, text) with const text = new Ref(""), then Number(text.value). The tail takes at most twelve arguments.
  • A plugin's own natives are its file's export functions, with the parameter types natives lists; another type stops the build.
  • A native of your own takes up to 64 arguments as Pawn passes them - an array or a string result counts twice, with its size; more stops the build: pass an array instead (natives).
  • A native that looks for the Pawn plugin calling it answers 0: a plugin's call has no Pawn plugin behind it, and the console says once what to write instead - set_task (setTimeout, setInterval), log_amx (console.log), register_clcmd and the other register_*cmd (server.addCommand), register_event and register_message (server.addMessageListener), register_logevent, RegisterHookChain, RegisterHam, register_forward, register_touch, register_think (the game's events), menu_create (Menu), hook_cvar_change and set_pcvar_bounds (a Cvar), register_native (export function), AutoExecConfig, set_fail_state, register_plugin, callfunc_begin (PawnFunction), trace_hull; engfunc with EngFunc_ChangeLevel, and the file natives with the game's file system (use_valve_fs). publicFor names a handler for register_menucmd and a PawnFunction call alone.
  • A buffer's length is never negative: a native given a buffer and a length below 0 - the -1 that ArrayGetArray, ArrayPushArray and other cellarray natives read as "the whole item" - is not called and answers 0. Pass the buffer's own length.
  • lang.translate takes its arguments as strings: a number goes in as text, `${seconds}` (translations).

Players and entities

  • A value no name stands for - another plugin or a mod wrote it - reads as "unknown", and assigning "unknown" changes nothing. Read the number with the native: get_entvar(player.id, var_rendermode), or, on a server without ReAPI, the engine module's entity_get_int(player.id, EV_INT_rendermode).
  • Plain numbers: autoSwitchWeapon, shotgunReloadStage.
  • No property for: array members (m_rgAmmo, …; the weapons are player.items), var_controller, var_blending. Use get_member and set_member, or fakemeta's get_ent_data and set_ent_data on a server without ReAPI (entities).
  • A vector or a text field read through a native needs its type:get_entvar<Vector>(id, var_origin), get_member<string>(id, m_szAnimExtention). Without it the field reads as a number, and a vector or text field reads as 0, with a line in the console that says what to write.
  • A flag list writes back through push only: pop and splice change the array, not the game. To remove a flag, assign a filtered array (flags).
  • Shared player fields are boolean, number, string, a union of string literals, Player[] or an object of those; never optional, and an object's members are not objects. A name Player already has is refused.
  • Shared entity fields since v0.3.1 are boolean, number, string or a union of string literals: not Player[] nor an object, and no change event. Keep a list or an object as several fields, and the plugin that writes a field tells the others itself (an exported function) (entity fields).

Effects

  • No effect for decals (a bullet hole, a spray - they need a decal's index), for the engine's tracer colours or for a text message (player.showHud is that); send them with message_begin and write_* (effects).
  • Too many effects for a player's packet are said on ReHLDS only: on Valve's HLDS the server cannot read what waits for a player; count what a frame sends (effects).

HTTP

  • A request's body is text: body takes a string - JSON.stringify(value), or an object through useFetch; not a FormData, Blob, ArrayBuffer or URLSearchParams. A form goes as text: body: query.toString() with "Content-Type": "application/x-www-form-urlencoded" (HTTP).
  • Headers are given as an object of names and values, not as a Headers or a list of pairs.
  • new URLSearchParams takes an object, not a query as text: read one with new URL(address).searchParams.
  • No response.body stream: a response is read whole, so a download or an upload has no progress to follow.
  • useFetch's query takes text: { page: `${page}` }.

FTP and SFTP

  • An SSH key is RSA in PEM: ssh-keygen -t rsa -m PEM. Keys in OpenSSH's own format (BEGIN OPENSSH PRIVATE KEY, what ssh-keygen writes by default), ECDSA and Ed25519 keys are not read, and a server whose only host key is Ed25519 cannot be reached. Convert an RSA key with ssh-keygen -p -m PEM -f key (network requests).

Databases

  • A value is text, a number, a boolean or null: a Date does not build in a query's values. Give it as text, date.toISOString(), or as a number, date.getTime() (database).
  • A binary column reads as text: BLOB and BINARY arrive as UTF-8 text, and bytes that are not UTF-8 are lost. Keep binary data as base64 text, or select it with HEX(column).
  • SQLite, PostgreSQL and the rest have no provider of their own: only mysql:// is built in. Another database is a provider a library or the plugin registers (other databases).
  • A query of the builder reads one table: joins, subqueries and SQL's functions in a value - LEAST(time, ?) in an upsert - go through raw SQL, db.query and db.execute.
  • A boolean field of your own insert's or update's object is read back with as: const row: typeof players.$inferInsert = { ... } then row.vip as boolean. The builder reads it as it is; a row read from the table is plain boolean.

Configs

  • The build reads the shape from the source, and refuses, with the place and the fix: an empty list without a type, a defaults variable without a declared type, a list of lists of lists or of objects, a Map of lists or objects, a union that is not of names (number | string), a generic interface or one that extends another, a field named with a string, a type that contains itself.
  • A Map's keys have no . and no [: such a key cannot be read or written.
  • YAML is the part configs use. Not read: anchors and aliases (&, *), tags (!), complex keys (?), directives, several documents, a plain value that goes on for several lines (quote it, or use | or >), tabs in indentation, a key written twice, a key inside [ ]. Each is an error with the file, line and column, and the file reads as empty.
  • Saving writes a YAML list written [a, b] one item per line, and drops a comment after a value on its line and comments inside { } and [ ]. Comments on lines of their own and blank lines are kept.

Shared modules

The details are on shared modules.

  • What cannot cross between plugins does not build: a Map, a Set, a generic class, a class from the standard library, a type the module does not export, a computed default, a generic or async function, an exported variable (export let count) - an object of a class of the module's own (export const counter = new Counter()) does cross.
  • An array or object field of a shared object reads as a copy: push on it changes the copy. Use the module's method, or assign the whole field.

Modules and the amxts command

  • A module gives one name: itself as a namespace (imports: [{ from, as }]) or one of its exports (imports: [{ from, name }]) - not a list of its functions or types; menus.Menu is a type of the namespace.
  • A module's meta, requires, defaults and imports are literals: the build reads them without running the module. Besides setup, defineModule has no lifecycle hooks: listen to server events inside setup.
  • A native the fake server does not answer stops the test with its name; answer it with server.defineNative(name, native) in the test, or in a module's test kit.

The editor

  • The build and amxts typecheck use TypeScript 5, the one the core installs; the editor works with TypeScript 5.9, 6 and 7.
  • A field the editor accepts may be missing in the build: the editor sees the fields every file of the plugins folder adds to Player, the build only those of the files the plugin imports. Add the import of the file that declares it.
  • Live help in menu files is for VS Code only, through the amxts extension (menus).