[Nord1cWarr1or]

🖤

Purpose

The vendored reapi/include/vtc_api.h had drifted from the actual VoiceTranscoder module (2017RC5, API 3.1): 3.0-era Get* naming, and no declarations for the block API the module has exposed since 3.1. Pawn plugins had no way to hard-block a client's voice.

Approach

• Header sync. vtc_api.h replaced with the real module header: MajorVersion()/MinorVersion() naming plus the previously missing BlockClient() / UnblockClient() / IsClientBlocked(). The vtable slot order for slots 0–9 is unchanged, so existing binaries keep working against both API 3.0 and 3.1 modules.

• New natives, guarded at runtime by the cached minor version — on VTC < 3.1 they log an error and return FALSE instead of risking a vtable overrun:

  • native VTC_BlockClient(const index);
  • native VTC_UnblockClient(const index);
  • native bool:VTC_IsClientBlocked(const index);

  Unlike VTC_MuteClient, which drops the voice at distribution stage (speaking events still fire), BlockClient drops the voice packets at parse time — the player is not treated as speaking at all (Main.cpp:646 vs :869).

• VTC_PlaySound broadcast. The VTC API natively treats receiver = 0 as "play to all clients" (client = nullptr skips the per-destination filter), but the adapter rejected it via CHECK_ISPLAYER. The check is now 0..maxClients, so plugins can broadcast.

• Compatibility. The minor-version gate in VTC_Api_Init() is gone entirely: VTC 3.0 modules keep working (all pre-existing natives unaffected), and only the new block natives require API ≥ 3.1 — they report the error when a plugin actually calls them, so nothing is printed at startup just because an older VTC is installed. Running an older VTC is the server owner's choice; the mechanism gates on use, not on install.

Open Questions and Pre-Merge TODOs

• Builds cleanly on Linux 32-bit — only the pre-existing harmless DT_TEXTREL ld warning.
• Collision sweep for the VTC_Block* native names — clean.
• Behavior verified statically against the VTC 3.1 sources (API.cpp, Main.cpp); the 3.0 path is covered by the runtime guard.
• Native declarations update the matching .inc in this same PR; the general docs overhaul (docs: overhaul Pawn include documentation #395) keeps only the current-behavior notes.
• Branch merged with current master; the only conflict was a doc block in reapi_vtc.inc rewritten by docs: overhaul Pawn include documentation #395 — resolved by keeping the receiver = 0 note, so the file differs from master only by the block natives and that note.

Learning

Ground truth: VoiceTranscoder 2017RC5 sources (API.cpp, Main.cpp); indices are 1-based everywhere; PlaySound takes a gamedir-relative PCM WAV path. A companion finding in the VTC module itself — an unbounded fgetc chunk scan in PlaySound that hangs on a non-WAV file — will be reported to the VTC maintainer separately.

See also: #395