@amxts/core 0.2.3 → 0.3.0

package/scripts/docs/as/fetch.ts

@@ -543,7 +543,7 @@ export default {
 
 			const { data, error } = await useFetch<Weather>("https://example.com/weather", { query: { city: "Paris" } });
 			if (error) return console.error(error.message);
-			print(player, \`\${data!.temperature} °C\`);
+			player.print(\`\${data!.temperature} °C\`);
 			\`\`\`
 
 			A body that is an object goes as JSON: \`useFetch<Answer, Report>(url, { method: "POST", body: report })\`.
@@ -559,7 +559,7 @@ export default {
 
 			const { data, error } = await useFetch<Weather>("https://example.com/weather", { query: { city: "Paris" } });
 			if (error) return console.error(error.message);
-			print(player, \`\${data!.temperature} °C\`);
+			player.print(\`\${data!.temperature} °C\`);
 			\`\`\`
 
 			Тело-объект уходит как JSON: \`useFetch<Answer, Report>(url, { method: "POST", body: report })\`.

package/scripts/docs/as/fs.ts

@@ -31,21 +31,25 @@ export default {
 	},
 	'writeFileSync': {
 		en: `
-			Writes text to a file, replacing what was there; \`false\` when it cannot be
-			opened (a folder that does not exist, for one).
+			Writes text, or bytes - a \`Uint8Array\` or an \`ArrayBuffer\` - to a file,
+			replacing what was there; \`false\` when it cannot be opened (a folder that
+			does not exist, for one). Bytes are not written past the game folder.
 
 			\`\`\`ts
 			fs.writeFileSync("addons/amxmodx/data/last-map.txt", server.map);
+			fs.writeFileSync("maps/kz_map.bsp", await response.arrayBuffer());
 			\`\`\`
 
 			Pawn: \`fopen\`, \`fputs\`
 		`,
 		ru: `
-			Записывает текст в файл вместо того, что там было; \`false\`, если файл не
-			удалось открыть (например, такой папки нет).
+			Записывает текст или байты — \`Uint8Array\` или \`ArrayBuffer\` — в файл
+			вместо того, что там было; \`false\`, если файл не удалось открыть (например,
+			такой папки нет). Байты не пишутся за пределы папки игры.
 
 			\`\`\`ts
 			fs.writeFileSync("addons/amxmodx/data/last-map.txt", server.map);
+			fs.writeFileSync("maps/kz_map.bsp", await response.arrayBuffer());
 			\`\`\`
 
 			Pawn: \`fopen\`, \`fputs\`
@@ -53,16 +57,70 @@ export default {
 	},
 	'appendFileSync': {
 		en: `
-			Adds text to the end of a file, making it if there is none; \`false\` when it cannot be opened.
+			Adds text or bytes to the end of a file, making it if there is none; \`false\` when it cannot be opened.
 
 			Pawn: \`fopen(path, "a")\`, \`fputs\`
 		`,
 		ru: `
-			Дописывает текст в конец файла, создавая его, если файла нет; \`false\`, если его не удалось открыть.
+			Дописывает текст или байты в конец файла, создавая его, если файла нет; \`false\`, если его не удалось открыть.
 
 			Pawn: \`fopen(path, "a")\`, \`fputs\`
 		`,
 	},
+	'readBytesSync': {
+		en: `
+			Reads a whole file as bytes; \`null\` when it cannot be opened or the path
+			leaves the game folder.
+		`,
+		ru: `
+			Читает весь файл как байты; \`null\`, если его не удалось открыть или путь
+			ведёт за пределы папки игры.
+		`,
+	},
+	'readBytes': {
+		en: `\`readBytesSync\` as a promise, rejected when the file cannot be opened.`,
+		ru: `\`readBytesSync\` в виде промиса; отклоняется, если файл не удалось открыть.`,
+	},
+	'ArchiveEntry': {
+		en: `A file of an archive, from \`extract\`: its path inside the archive and its bytes.`,
+		ru: `Файл архива из \`extract\`: его путь внутри архива и его байты.`,
+	},
+	'ArchiveEntry.path': {
+		en: `The path inside the archive, \`/\` between folders: \`"maps/de_dust2.bsp"\`.`,
+		ru: `Путь внутри архива, \`/\` между папками: \`"maps/de_dust2.bsp"\`.`,
+	},
+	'ArchiveEntry.data': {
+		en: `The file's bytes.`,
+		ru: `Байты файла.`,
+	},
+	'extract': {
+		en: `
+			The files of an archive, with their paths inside it; folders are not
+			listed. The archive's kind is read off its first bytes: a zip archive,
+			stored or deflated. Throws an \`Error\` for a kind it does not read - naming
+			the ones it does - an entry whose bytes do not check out, and a path that
+			would leave the folder it is unpacked into.
+
+			\`\`\`ts
+			for (const entry of fs.extract(await response.arrayBuffer())) {
+				fs.writeFileSync(entry.path, entry.data);
+			}
+			\`\`\`
+		`,
+		ru: `
+			Файлы архива с их путями внутри него; папки не перечисляются. Вид архива
+			читается по его первым байтам: zip-архив, сохранённый как есть или сжатый
+			deflate. Бросает \`Error\` для вида, который не читает, — называя те, что
+			читает, — для файла, чьи байты не сходятся, и для пути, который ведёт за
+			пределы папки, куда архив распаковывается.
+
+			\`\`\`ts
+			for (const entry of fs.extract(await response.arrayBuffer())) {
+				fs.writeFileSync(entry.path, entry.data);
+			}
+			\`\`\`
+		`,
+	},
 	'existsSync': {
 		en: `
 			\`true\` when the file or folder exists.
@@ -170,4 +228,130 @@ export default {
 		en: `\`readdirSync\` as a promise, rejected when there is no such folder.`,
 		ru: `\`readdirSync\` в виде промиса; отклоняется, если такой папки нет.`,
 	},
+	'unlinkSync': {
+		en: `
+			Deletes a file; \`false\` when there is none or it cannot be deleted.
+
+			Pawn: \`delete_file\`, \`unlink\`
+		`,
+		ru: `
+			Удаляет файл; \`false\`, если его нет или его не удалось удалить.
+
+			Pawn: \`delete_file\`, \`unlink\`
+		`,
+	},
+	'renameSync': {
+		en: `
+			Moves or renames a file: \`fs.renameSync("addons/amxmodx/data/top.txt",
+			"addons/amxmodx/data/top.old")\`; \`false\` when it cannot.
+
+			Pawn: \`rename_file\`
+		`,
+		ru: `
+			Перемещает или переименовывает файл: \`fs.renameSync("addons/amxmodx/data/top.txt",
+			"addons/amxmodx/data/top.old")\`; \`false\`, если не удалось.
+
+			Pawn: \`rename_file\`
+		`,
+	},
+	'rmdirSync': {
+		en: `
+			Deletes an empty folder; \`false\` when there is none, it holds something or
+			it cannot be deleted.
+
+			Pawn: \`rmdir\`
+		`,
+		ru: `
+			Удаляет пустую папку; \`false\`, если её нет, в ней что-то есть или её не
+			удалось удалить.
+
+			Pawn: \`rmdir\`
+		`,
+	},
+	'Stats': {
+		en: `
+			A file's or a folder's facts from \`statSync\`, as Node's \`fs.Stats\`.
+		`,
+		ru: `
+			Сведения о файле или папке из \`statSync\`, как \`fs.Stats\` в Node.
+		`,
+	},
+	'Stats.size': {
+		en: `
+			The size in bytes; \`0\` for a folder.
+		`,
+		ru: `
+			Размер в байтах; \`0\` для папки.
+		`,
+	},
+	'Stats.mtime': {
+		en: `
+			The moment it last changed.
+		`,
+		ru: `
+			Момент его последнего изменения.
+		`,
+	},
+	'Stats.isFile': {
+		en: `
+			Whether it is a file.
+		`,
+		ru: `
+			Файл ли это.
+		`,
+	},
+	'Stats.isDirectory': {
+		en: `
+			Whether it is a folder.
+		`,
+		ru: `
+			Папка ли это.
+		`,
+	},
+	'statSync': {
+		en: `
+			A file's or a folder's size and the moment it last changed; \`null\` when
+			there is none: \`fs.statSync("addons/amxmodx/logs/error.log")?.size\`.
+
+			Pawn: \`file_size\`, \`GetFileTime\`
+		`,
+		ru: `
+			Размер файла или папки и момент последнего изменения; \`null\`, если их нет:
+			\`fs.statSync("addons/amxmodx/logs/error.log")?.size\`.
+
+			Pawn: \`file_size\`, \`GetFileTime\`
+		`,
+	},
+	'unlink': {
+		en: `
+			\`unlinkSync\` as a promise, rejected when the file cannot be deleted.
+		`,
+		ru: `
+			\`unlinkSync\` в виде промиса; отклоняется, если файл не удалось удалить.
+		`,
+	},
+	'rename': {
+		en: `
+			\`renameSync\` as a promise, rejected when the file cannot be moved.
+		`,
+		ru: `
+			\`renameSync\` в виде промиса; отклоняется, если файл не удалось переместить.
+		`,
+	},
+	'rmdir': {
+		en: `
+			\`rmdirSync\` as a promise, rejected when the folder cannot be deleted.
+		`,
+		ru: `
+			\`rmdirSync\` в виде промиса; отклоняется, если папку не удалось удалить.
+		`,
+	},
+	'stat': {
+		en: `
+			\`statSync\` as a promise, rejected when there is no such file or folder.
+		`,
+		ru: `
+			\`statSync\` в виде промиса; отклоняется, если такого файла или папки нет.
+		`,
+	},
 };

package/scripts/docs/as/vector.ts

@@ -45,4 +45,85 @@ export default {
 		en: `A new vector in the same direction, one unit long; a zero vector stays zero.`,
 		ru: `Новый вектор того же направления, длиной в единицу; нулевой вектор так и остаётся нулевым.`,
 	},
+	'Vector.fromAngles': {
+		en: `
+			The direction angles look in, one unit long:
+			\`Vector.fromAngles(player.viewAngle).scale(500)\` is a push the way the
+			player looks.
+
+			Pawn: \`angle_vector(..., ANGLEVECTOR_FORWARD, ...)\`, \`velocity_by_aim\`
+		`,
+		ru: `
+			Направление, куда смотрят углы, длиной в единицу:
+			\`Vector.fromAngles(player.viewAngle).scale(500)\` — толчок туда, куда смотрит
+			игрок.
+
+			Pawn: \`angle_vector(..., ANGLEVECTOR_FORWARD, ...)\`, \`velocity_by_aim\`
+		`,
+	},
+	'Vector.directions': {
+		en: `
+			The three directions of angles, one unit long each: where they look,
+			to their right and above them - \`const { forward, right } =
+			Vector.directions(player.viewAngle)\`.
+
+			Pawn: \`angle_vector\`, \`engfunc(EngFunc_MakeVectors, ...)\`
+		`,
+		ru: `
+			Три направления углов, каждое длиной в единицу: куда они смотрят, вправо от
+			них и вверх — \`const { forward, right } = Vector.directions(player.viewAngle)\`.
+
+			Pawn: \`angle_vector\`, \`engfunc(EngFunc_MakeVectors, ...)\`
+		`,
+	},
+	'Vector.toAngles': {
+		en: `
+			The angles that look along this vector, as a player's view holds them -
+			a pitch below the horizon positive: \`player.viewAngle =
+			target.subtract(player.eyes).toAngles()\`. \`Vector.fromAngles\` turns
+			them back.
+
+			Pawn: \`vector_to_angle\`, \`engfunc(EngFunc_VecToAngles, ...)\`
+		`,
+		ru: `
+			Углы, которые смотрят вдоль этого вектора, как их держит взгляд игрока, —
+			наклон ниже горизонта положительный: \`player.viewAngle =
+			target.subtract(player.eyes).toAngles()\`. \`Vector.fromAngles\` превращает их
+			обратно.
+
+			Pawn: \`vector_to_angle\`, \`engfunc(EngFunc_VecToAngles, ...)\`
+		`,
+	},
+	'Directions': {
+		en: `
+			The three directions of angles: ahead, to the right and up - \`Vector.directions\`.
+		`,
+		ru: `
+			Три направления углов: вперёд, вправо и вверх — \`Vector.directions\`.
+		`,
+	},
+	'Directions.forward': {
+		en: `
+			The direction they look in.
+		`,
+		ru: `
+			Направление, куда они смотрят.
+		`,
+	},
+	'Directions.right': {
+		en: `
+			To their right.
+		`,
+		ru: `
+			Вправо от них.
+		`,
+	},
+	'Directions.up': {
+		en: `
+			Above them.
+		`,
+		ru: `
+			Вверх от них.
+		`,
+	},
 };

package/scripts/docs/entities.ts

@@ -737,6 +737,10 @@ export const ENTITY_FIELDS: Record<string, Text> = {
 		en: `The player's field of view in degrees: \`90\` is normal, \`40\` and \`10\` through a sniper scope. Setting it widens or narrows his view - \`110\` shows more - until the game sets it again: at spawn, when he draws a weapon, when he zooms.`,
 		ru: `Поле зрения игрока в градусах: \`90\` — обычное, \`40\` и \`10\` — в снайперский прицел. Запись расширяет или сужает обзор — \`110\` показывает больше, — пока игра не поставит своё: при появлении, когда он достаёт оружие, когда приближает прицел.`,
 	},
+	m_flFallVelocity: {
+		en: `The player's falling speed, units per second, positive downwards: the one the game works fall damage out from on landing. Setting it sets the entity's \`fallVelocity\` too - \`player.fallVelocity = 0\` lands him without damage.`,
+		ru: `Скорость падения игрока, единиц в секунду, вниз положительная: по ней игра считает урон при приземлении. Запись ставит и \`fallVelocity\` сущности — \`player.fallVelocity = 0\` приземляет без урона.`,
+	},
 	m_iLastZoom: {
 		en: `The player's zoom (field of view) to go back to after a sniper rifle reloads or fires.`,
 		ru: `Зум игрока (поле зрения), к которому вернуться после перезарядки или выстрела снайперской винтовки.`,
@@ -1983,6 +1987,14 @@ Pawn: \`is_valid_ent\`, \`is_entity\``,
 		ru: `\`true\`, пока сущность есть в мире: \`false\`, когда движок её освободил (\`remove()\` освобождает её в конце кадра), для ушедшего игрока и для \`0\` — «нет сущности». Номер из события или хука может указывать на сущность, которой уже нет.
 
 Pawn: \`is_valid_ent\`, \`is_entity\``,
+	},
+	'Entity.dropToFloor': {
+		en: `Drops the entity straight down onto what is under it, as the game puts an item on the floor when a map starts: \`true\` when it landed, \`false\` when there is nothing under it within 256 units or it is stuck in something.
+
+Pawn: \`drop_to_floor\`, \`engfunc(EngFunc_DropToFloor, ...)\``,
+		ru: `Опускает сущность вертикально вниз на то, что под ней, как игра кладёт предмет на пол при старте карты: \`true\`, если она опустилась, \`false\`, если под ней ничего нет в пределах 256 единиц или она во что-то застряла.
+
+Pawn: \`drop_to_floor\`, \`engfunc(EngFunc_DropToFloor, ...)\``,
 	},
 	'Entity.emitSound': {
 		en: `Plays a sound from the entity, heard by everyone near and fading with distance: \`player.emitSound("myplugin/hit.wav")\`. The path is under \`sound/\`, as \`server.precache\` takes it; \`options\` set the channel, the volume, the attenuation and the pitch.

package/scripts/docs/events.ts

@@ -1,6 +1,6 @@
 // Our own words for the server events, in both languages the project speaks.
 //
-// scripts/generate-host.ts writes these into as/events.ts as the tooltips an
+// scripts/generate-image.ts writes these into as/events.ts as the tooltips an
 // editor shows on `server.addEventListener("...")`, on the event class and on
 // each of its fields. The language is AMXTS_DOCS_LANG in .env ("en" by
 // default, or "ru"). An event missing here, or missing a language, falls back
@@ -59,16 +59,10 @@ export const EVENTS: Record<string, EventDoc> = {
 	},
 	plugin_end: {
 		summary: {
-			en: `The map is ending or the server is shutting down: save what has to survive.`,
-			ru: `Карта заканчивается или сервер выключается: сохраните то, что должно пережить смену карты.`,
+			en: `The plugin stops - the map ends, the server shuts down, or \`amxts_reload\`/\`amxts_unload\` stops it: save what has to survive.`,
+			ru: `Плагин останавливается — карта заканчивается, сервер выключается или его останавливает \`amxts_reload\`/\`amxts_unload\`: сохраните то, что должно это пережить.`,
 		},
 	},
-	plugin_pause: {
-		summary: { en: `An admin paused this plugin.`, ru: `Админ поставил плагин на паузу.` },
-	},
-	plugin_unpause: {
-		summary: { en: `An admin resumed this plugin.`, ru: `Админ снял плагин с паузы.` },
-	},
 	server_changelevel: {
 		summary: {
 			en: `The server is about to change the map.`,
@@ -78,6 +72,23 @@ export const EVENTS: Record<string, EventDoc> = {
 			map: { en: `The map the server changes to, e.g. \`"de_dust2"\`.`, ru: `Карта, на которую переходит сервер, например \`"de_dust2"\`.` },
 		},
 	},
+	plugin_log: {
+		summary: {
+			en: `A line the game writes to its log - a round's end, a kill, a bomb planted: \`event.text\` whole, \`event.args\` its parts.`,
+			ru: `Строка, которую игра пишет в свой лог, — конец раунда, убийство, заложенная бомба: \`event.text\` целиком, \`event.args\` по частям.`,
+		},
+		fields: {
+			text: {
+				en: `The line as the game logs it, without the date: \`World triggered "Round_Start"\`.`,
+				ru: `Строка так, как её пишет игра, без даты: \`World triggered "Round_Start"\`.`,
+			},
+			args: {
+				en: `The line in parts, as AMX Mod X splits it: a quoted text, a text in parentheses and the words between, each one part - \`World triggered "Round_Draw"\` is \`["World triggered", "Round_Draw"]\`.`,
+				ru: `Строка по частям, как её делит AMX Mod X: текст в кавычках, текст в скобках и слова между ними — каждое отдельной частью; \`World triggered "Round_Draw"\` — это \`["World triggered", "Round_Draw"]\`.`,
+			},
+		},
+		example: `server.addEventListener("log", (event) => {\n\tif (event.text.startsWith("World triggered")) console.log(event.args[1]);\n});`,
+	},
 	client_connect: {
 		summary: {
 			en: `A player started connecting. The player is not in the game yet: show him anything after \`"putInServer"\`.`,
@@ -117,7 +128,7 @@ export const EVENTS: Record<string, EventDoc> = {
 			ru: `Игрок зашёл и уже в игре: момент поприветствовать его.`,
 		},
 		fields: { player },
-		example: `server.addEventListener("putInServer", (event) => {\n\tprint(event.player, "Welcome!");\n});`,
+		example: `server.addEventListener("putInServer", (event) => {\n\tevent.player.print("Welcome!");\n});`,
 	},
 	client_disconnected: {
 		summary: {
@@ -154,10 +165,30 @@ export const EVENTS: Record<string, EventDoc> = {
 	},
 	client_command: {
 		summary: {
-			en: `A player sent a console command. For one command, \`server.addCommand("name", handler)\` is simpler.`,
-			ru: `Игрок отправил консольную команду. Для одной команды проще \`server.addCommand("name", handler)\`.`,
+			en: `A player sent a console command - a chat line is \`say\` or \`say_team\`. For one command, \`server.addCommand("name", handler)\` is simpler.`,
+			ru: `Игрок отправил консольную команду — строка в чат это \`say\` или \`say_team\`. Для одной команды проще \`server.addCommand("name", handler)\`.`,
 		},
-		fields: { player },
+		notes: [],
+		fields: {
+			player,
+			command: {
+				en: `The command's name, as typed, e.g. \`"say"\`, \`"say_team"\`, \`"buy"\`.`,
+				ru: `Имя команды, как её ввели, например \`"say"\`, \`"say_team"\`, \`"buy"\`.`,
+			},
+			args: {
+				en: `The command's words after its name; for \`say\` and \`say_team\`, the words of the chat line - \`say /cp now\` is \`["/cp", "now"]\`.`,
+				ru: `Слова команды после имени; у \`say\` и \`say_team\` — слова строки чата: \`say /cp now\` — это \`["/cp", "now"]\`.`,
+			},
+			text: {
+				en: `The command's text after its name, as one line; for \`say\` and \`say_team\`, the chat line without its quotes.`,
+				ru: `Текст команды после имени одной строкой; у \`say\` и \`say_team\` — строка чата без кавычек.`,
+			},
+			preventDefault: {
+				en: `Stops the command: the game does not run it - a chat line is not said - and no plugin's \`server.addCommand\` hears it. The other listeners of \`"command"\` still do.`,
+				ru: `Останавливает команду: игра её не выполняет — строка чата не уходит в чат, — и её не слышит ни один \`server.addCommand\` плагинов. Остальные слушатели \`"command"\` её слышат.`,
+			},
+		},
+		example: `server.addEventListener("command", (event) => {\n\tif (event.command == "say" && event.args[0] == "/cp") checkpoint(event.player);\n});`,
 	},
 	client_infochanged: {
 		summary: {
@@ -221,6 +252,11 @@ export const EVENTS: Record<string, EventDoc> = {
 			iparam2: { en: `The event's second whole-number parameter.`, ru: `Второй целый параметр события.` },
 			bparam1: { en: `The event's first flag parameter, \`1\` or \`0\`.`, ru: `Первый параметр-флаг события, \`1\` или \`0\`.` },
 			bparam2: { en: `The event's second flag parameter, \`1\` or \`0\`.`, ru: `Второй параметр-флаг события, \`1\` или \`0\`.` },
+			preventDefault: { en: `Stops the event: no player gets it - a shot's sound and flash with it.`, ru: `Останавливает событие: его не получает ни один игрок — вместе со звуком и вспышкой выстрела.` },
+			recipients: {
+				en: `Plays the event only to these of the players it would reach - \`event.recipients = players.filter(...)\`; the others do not hear the shot. The player who caused it is not left out by it.`,
+				ru: `Проигрывает событие только этим из игроков, до которых оно дошло бы, — \`event.recipients = players.filter(...)\`; остальные не слышат выстрела. Игрока, из-за которого оно случилось, это не исключает.`,
+			},
 		},
 	},
 };

package/scripts/docs/game.ts

@@ -30,6 +30,12 @@ const theWeapon: Text = { en: `The weapon the event is about - one of the class
 const theEntity: Text = { en: `The entity the event is about - one of the class \`classname\` names.`, ru: `Сущность, о которой событие, — одного класса, названного в \`classname\`.` };
 
 export const GAME: Record<string, GameDoc> = {
+	entityState: {
+		summary: {
+			en: `The state of an entity a player can see, as he is sent it each frame: its place, angles, look - written for him alone - or hidden from him with \`event.preventDefault()\`. \`{ classname }\` names the entities a listener is about; the module passes only those.`,
+			ru: `Состояние сущности, которую видит игрок, как он получает его каждый кадр: её место, углы, вид — изменённые только для него, — или скрытая от него через \`event.preventDefault()\`. \`{ classname }\` называет сущности, о которых слушатель; модуль передаёт только их.`,
+		},
+	},
 	touch: {
 		summary: {
 			en: `An entity touched another: \`event.toucher\` moved into \`event.touched\`. Pass the classes it is about as the third argument - \`{ toucher: "player", touched: "player" }\` - so only those touches reach the plugin; \`event.preventDefault()\` blocks the touch.`,

package/scripts/docs/messages.ts

@@ -1,6 +1,6 @@
 // Our own words for the messages the server sends its clients, as
 // server.addMessageListener(name, ...) hears them - in both languages.
-// scripts/generate-host.ts writes them into as/events.ts as the tooltips an
+// scripts/generate-image.ts writes them into as/events.ts as the tooltips an
 // editor shows on the name, the event and its fields: the summary, then the
 // game's name of the message, so a Pawn author who searches for `DeathMsg`
 // finds `death`. A name that hears a few of the game's messages has its words
@@ -427,6 +427,7 @@ export const MESSAGES: Record<string, EventDoc> = {
 			slot: { en: `The slot the weapon is in, from \`0\`.`, ru: `Слот оружия, с \`0\`.` },
 			position: { en: `The weapon's place in the slot, from \`0\`.`, ru: `Место оружия в слоте, с \`0\`.` },
 			weapon: { en: `The weapon, by its kind, e.g. \`"ak47"\`.`, ru: `Оружие по его виду, например \`"ak47"\`.` },
+			flags: { en: `The weapon's ITEM_FLAG_* bits: \`8\` for one thrown when it is empty, \`16\` for one used only once.`, ru: `Биты ITEM_FLAG_* оружия: \`8\` — выбрасывается, когда пусто, \`16\` — используется один раз.` },
 		},
 	},
 	WeapPickup: {
@@ -460,3 +461,11 @@ export const ANY_MESSAGE: { args: Text; player: Text } = {
 	args: { en: `Its arguments are read by place, through \`event.args\`.`, ru: `Его аргументы читаются по месту, через \`event.args\`.` },
 	player: receiver,
 };
+
+/** The words of a message's fields for sending: what player.send and server.send take for a name. */
+export function sendFields(name: string, message: string): Text {
+	return {
+		en: `What \`player.send("${name}", ...)\` and \`server.send("${name}", ...)\` take: the game's \`${message}\` message, each field one of its arguments. A field left out goes as \`0\` or empty text.\n\nPawn: \`message_begin(..., get_user_msgid("${message}"))\`, \`write_*\`, \`message_end\``,
+		ru: `Что принимают \`player.send("${name}", ...)\` и \`server.send("${name}", ...)\`: сообщение игры \`${message}\`, каждое поле — один его аргумент. Пропущенное поле уходит как \`0\` или пустой текст.\n\nPawn: \`message_begin(..., get_user_msgid("${message}"))\`, \`write_*\`, \`message_end\``,
+	};
+}

package/scripts/hlds-events.ts

@@ -43,8 +43,8 @@ function noAnswer(en: string, ru: string): Text {
 
 function buy(en: string, ru: string): Text {
 	return noAnswer(
-		`heard through cstrike's \`CS_OnBuy\`: \`preventDefault()\` stops the purchase; ${en}`,
-		`слышно через \`CS_OnBuy\` модуля cstrike: \`preventDefault()\` отменяет покупку; ${ru}`,
+		`heard as the game checks the purchase, for an item a buy command or a buy menu names: \`preventDefault()\` stops it; ${en}`,
+		`слышно, когда игра проверяет покупку, для предмета, который называет команда покупки или меню покупки: \`preventDefault()\` отменяет её; ${ru}`,
 	);
 }
 
@@ -79,7 +79,7 @@ export const HEARD: Record<string, HeardEvent> = {
 	},
 	gameThink: { class: 'B', backend: 'server_frame', gaps: after },
 	mapReset: { class: 'B', backend: 'the decal_reset.sc playback CleanUpMap ends with', gaps: after },
-	intermission: { class: 'B', backend: 'register_event "30" (SVC_INTERMISSION)', gaps: after },
+	intermission: { class: 'B', backend: 'the engine message 30 (SVC_INTERMISSION)', gaps: after },
 	changeLevel: { class: 'B', backend: 'server_changelevel', gaps: { en: '`preventDefault()` does nothing', ru: '`preventDefault()` ничего не делает' } },
 
 	// Spawning and dying.
@@ -138,15 +138,15 @@ export const HEARD: Record<string, HeardEvent> = {
 			'`amount` — на сколько сдвинулись его деньги с тех пор, как игра в последний раз их ему прислала, а `reason` читается как `"none"`',
 		),
 	},
-	buyWeapon: { class: 'B', backend: 'cstrike CS_OnBuy, a weapon', gaps: buy('`event.result` reads as `null`', '`event.result` читается как `null`') },
-	buyItem: { class: 'B', backend: 'cstrike CS_OnBuy, the equipment', gaps: buy('heard for the equipment menu\'s items', 'слышно для предметов меню снаряжения') },
-	buyAmmo: { class: 'B', backend: 'cstrike CS_OnBuy, ammo', gaps: buy('`weapon` reads as the world, `blinkMoney` as `true`', '`weapon` читается как мир, `blinkMoney` — как `true`') },
+	buyWeapon: { class: 'B', backend: 'the game\'s CanBuyThis, a weapon (CS_OnBuy\'s place)', gaps: buy('`event.result` reads as `null`', '`event.result` читается как `null`') },
+	buyItem: { class: 'B', backend: 'the game\'s CanPlayerBuy and GiveNamedItem, the equipment (CS_OnBuy\'s place)', gaps: buy('heard for the equipment menu\'s items', 'слышно для предметов меню снаряжения') },
+	buyAmmo: { class: 'B', backend: 'the game\'s GiveNamedItem, ammo (CS_OnBuy\'s place)', gaps: buy('`weapon` reads as the world, `blinkMoney` as `true`', '`weapon` читается как мир, `blinkMoney` — как `true`') },
 	itemRestricted: {
 		class: 'B',
-		backend: 'cstrike CS_OnBuyAttempt',
+		backend: 'the game\'s ClientCommand, a buy command or a buy menu\'s number (CS_OnBuyAttempt\'s place)',
 		gaps: {
-			en: 'asked only for `"buying"`, through cstrike\'s `CS_OnBuyAttempt`: answering `true` forbids the purchase, `false` lets the game go on',
-			ru: 'спрашивается только про `"buying"`, через `CS_OnBuyAttempt` модуля cstrike: ответ `true` запрещает покупку, `false` оставляет решение игре',
+			en: 'asked only for `"buying"`, as a player asks to buy: answering `true` forbids the purchase, `false` lets the game go on',
+			ru: 'спрашивается только про `"buying"`, когда игрок просит покупку: ответ `true` запрещает покупку, `false` оставляет решение игре',
 		},
 	},
 
@@ -234,7 +234,7 @@ export const HEARD: Record<string, HeardEvent> = {
 		},
 	},
 
-	// Precaching: fakemeta's forwards, added at plugin_precache, before the game's own.
+	// Precaching: the engine's functions, hooked as the plugin loads, before the game's own precaches.
 	precacheModel: { class: 'B', backend: 'FM_PrecacheModel', gaps: precached },
 	precacheSound: { class: 'B', backend: 'FM_PrecacheSound', gaps: precached },
 	precacheFile: { class: 'B', backend: 'FM_PrecacheGeneric', gaps: precached },
@@ -341,7 +341,7 @@ export interface HeardField {
 }
 
 export const HEARD_FIELDS: Record<string, HeardField> = {
-	gameName: { class: 'A', backend: 'fakemeta: GetGameDescription read, and answered with the text written' },
+	gameName: { class: 'A', backend: 'the game\'s GetGameDescription read, and answered with the text written' },
 	timeLimit: {
 		class: 'B',
 		backend: 'mp_timelimit and AMX Mod X\'s time left',

package/scripts/includes.ts

@@ -14,9 +14,8 @@
  * includes/ and AMX Mod X's. The core's includes/vendor/ is the core's own:
  * a project sees what its server has.
  *
- * Everything available is parsed for its natives, but the host plugin pulls only
- * what order.txt lists: referencing a native of a module the server does not
- * load makes AMX Mod X refuse the plugin, and the runtime goes down with it.
+ * Everything available is parsed for its natives, but the natives' image
+ * pulls only what order.txt lists.
  */
 import { realpathSync } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -91,7 +90,7 @@ export function readInclude(name: string): string {
 }
 
 /**
- * Parses includes/order.txt. A bare name is included and (by the host
+ * Parses includes/order.txt. A bare name is included and (by the image's
  * generator) pulled; a line starting with `-` is a deny marker - the name
  * still has to resolve (an include that #includes it needs it on disk), but
  * it is excluded from whatever build the caller pulls into a native table.