Skip to content

bvm-reference.md

Latest commit

 

History

History
349 lines (302 loc) · 17.4 KB

bvm-reference.md

File metadata and controls

349 lines (302 loc) · 17.4 KB

BVM scripting reference

Generated by scripts/gen_bvm_reference.sh from src/Modules/RC_Standard_Invoker.bb and src/Modules/ScriptingCommands.bb. Do not edit this file by hand — rerun the generator after touching either source file.

This is the catalog of native functions callable from .rsl / .rcscript files that the embedded BVM (Blitz Virtual Machine) compiles and runs. For an overview of how scripts are loaded, dispatched, and gated, see docs/modules/scripting.md.

Privilege legend

Each entry shows the privilege gate enforced at the top of the BVM implementation. The gate determines whether the function is callable from a script spawned by an arbitrary clicker, or only from a script the server itself spawned (or from a DM / GM):

Gate Meaning
None Callable from any script. Pure-read or otherwise safe.
SelfOrPrivileged Callable if the target actor is the script's spawning actor (SI\AI) OR the script was spawned privileged. WRONG choice for any function that must block clicker exploits in Examine / Trade / RightClick / ItemScript spawns (where SI\AI = Handle(clicker)) — use Privileged instead.
Privileged Callable only from privileged scripts (server-spawned or DM-initiated). Mutates global state, opens host resources, or invokes terminal failures.
Dead Not callable — does nothing. The opcode survives in the dispatch table for opcode-number stability, but the implementation is permanently disabled (commented out in ScriptingCommands.bb, marked DEAD-API) and the dispatch case is a silent no-op. A script that calls it compiles and runs without error but has no effect; do not write new scripts against it.

See CLAUDE.md's "Privilege gating in BVM commands" section for the full threat model.

Sigil legend

The return-type sigil follows the BlitzForge convention: % = Int, $ = String, # = Float, none = void/Bool. Parameter sigils inside the argument list use the same.

Actor

Function Signature Gate
ACTOR ACTOR() : Int None
ACTORAGGRESSIVENESS ACTORAGGRESSIVENESS(PARAM1%) : Int None
ACTORAISTATE ACTORAISTATE(PARAM1%) : Int None
ACTORAMULET ACTORAMULET(PARAM1%, PARAM2%) : Int None
ACTORBACKPACK ACTORBACKPACK(PARAM1%, PARAM2%) : Int None
ACTORBEARD ACTORBEARD(PARAM1%) : Int None
ACTORBELT ACTORBELT(PARAM1%) : Int None
ACTORCALLFORHELP ACTORCALLFORHELP(PARAM1%) None
ACTORCHEST ACTORCHEST(PARAM1%) : Int None
ACTORCLOTHES ACTORCLOTHES(PARAM1%) : Int None
ACTORDESTINATIONX ACTORDESTINATIONX(PARAM1%) : Float None
ACTORDESTINATIONZ ACTORDESTINATIONZ(PARAM1%) : Float None
ACTORDISTANCE ACTORDISTANCE(PARAM1%, PARAM2%) : Float None
ACTORFACE ACTORFACE(PARAM1%) : Int None
ACTORFEET ACTORFEET(PARAM1%) : Int None
ACTORGENDER ACTORGENDER(PARAM1%) : Int None
ACTORGLOBAL ACTORGLOBAL(PARAM1%, PARAM2%) : String None
ACTORGROUP ACTORGROUP(PARAM1%) : Int None
ACTORGUILD ACTORGUILD(PARAM1%) : Int None
ACTORHAIR ACTORHAIR(PARAM1%) : Int None
ACTORHANDS ACTORHANDS(PARAM1%) : Int None
ACTORHASEFFECT ACTORHASEFFECT(PARAM1%, PARAM2$) : Int None
ACTORHAT ACTORHAT(PARAM1%) : Int None
ACTORID ACTORID(PARAM1$, PARAM2$) : Int None
ACTORIDFROMINSTANCE ACTORIDFROMINSTANCE(PARAM1%) : Int None
ACTORINTRIGGER ACTORINTRIGGER(PARAM1%, PARAM2%) : Int None
ACTORISHUMAN ACTORISHUMAN(PARAM1%) : Int None
ACTORLEADER ACTORLEADER(PARAM1%) : Int None
ACTORLEGS ACTORLEGS(PARAM1%) : Int None
ACTORLEVEL ACTORLEVEL(PARAM1%) : Int None
ACTORMOUNT ACTORMOUNT(PARAM1%) : Int None
ACTOROUTDOORS ACTOROUTDOORS(PARAM1%) : Int None
ACTORPETS ACTORPETS(PARAM1%) : Int None
ACTORRIDER ACTORRIDER(PARAM1%) : Int None
ACTORRING ACTORRING(PARAM1%, PARAM2%) : Int None
ACTORSHIELD ACTORSHIELD(PARAM1%) : Int None
ACTORSINZONE ACTORSINZONE(PARAM1$, INSTANCE%=0) : Int None
ACTORTARGET ACTORTARGET(PARAM1%) : Int None
ACTORUNDERWATER ACTORUNDERWATER(PARAM1%) : Int None
ACTORWEAPON ACTORWEAPON(PARAM1%) : Int None
ACTORX ACTORX(PARAM1%) : Float None
ACTORXP ACTORXP(PARAM1%) : Int None
ACTORXPMULTIPLIER ACTORXPMULTIPLIER(PARAM1%) : Int None
ACTORY ACTORY(PARAM1%) : Float None
ACTORZ ACTORZ(PARAM1%) : Float None
ACTORZONE ACTORZONE(PARAM1%) : String None
ACTORZONEINSTANCE ACTORZONEINSTANCE(PARAM1%) : Int None
MOVEACTOR MOVEACTOR(PARAM1%, PARAM2#, PARAM3#, PARAM4#, PARAM5%=0, PARAM6%=0) SelfOrPrivileged
ROTATEACTOR ROTATEACTOR(PARAM1%, PARAM2#) SelfOrPrivileged
SETACTORAISTATE SETACTORAISTATE(PARAM1%, PARAM2%) Privileged
SETACTORBEARD SETACTORBEARD(PARAM1%, PARAM2%) Privileged
SETACTORCLOTHES SETACTORCLOTHES(PARAM1%, PARAM2%) Privileged
SETACTORDESTINATION SETACTORDESTINATION(PARAM1%, PARAM2#, PARAM3#) SelfOrPrivileged
SETACTORFACE SETACTORFACE(PARAM1%, PARAM2%) Privileged
SETACTORGENDER SETACTORGENDER(PARAM1%, PARAM2%) Privileged
SETACTORGLOBAL SETACTORGLOBAL(PARAM1%, PARAM2%, PARAM3$) None
SETACTORGROUP SETACTORGROUP(PARAM1%, PARAM2%) Privileged
SETACTORGUILD SETACTORGUILD(PARAM1%, PARAM2%) Privileged
SETACTORHAIR SETACTORHAIR(PARAM1%, PARAM2%) Privileged
SETACTORLEVEL SETACTORLEVEL(PARAM1%, PARAM2%) Privileged
SETACTORTARGET SETACTORTARGET(PARAM1%, PARAM2%=0) Privileged
SPAWN SPAWN(PARAM1%, PARAM2$, PARAM3#, PARAM4#, PARAM5#, PARAM6$ = "", PARAM7$ = "", PARAM8%=0) : Int None

Item

Function Signature Gate
GIVEITEM GIVEITEM(PARAM1%, PARAM2$, PARAM3%=1) Privileged
ITEMARMOR ITEMARMOR(PARAM1%) : Int None
ITEMATTRIBUTE ITEMATTRIBUTE(PARAM1%, PARAM2$) : Int None
ITEMDAMAGE ITEMDAMAGE(PARAM1%) : Int None
ITEMDAMAGETYPE ITEMDAMAGETYPE(PARAM1%) : String None
ITEMHEALTH ITEMHEALTH(PARAM1%) : Int None
ITEMID ITEMID(PARAM1%) : Int None
ITEMMASS ITEMMASS(PARAM1%) : Int None
ITEMMISCDATA ITEMMISCDATA(PARAM1%) : String None
ITEMNAME ITEMNAME(PARAM1%) : String None
ITEMRANGE ITEMRANGE(PARAM1%) : Float None
ITEMVALUE ITEMVALUE(PARAM1%) : Int None
ITEMWEAPONTYPE ITEMWEAPONTYPE(PARAM1%) : Int None
SETITEMHEALTH SETITEMHEALTH(PARAM1%, PARAM2%) Privileged
SPAWNITEM SPAWNITEM(PARAM1$, PARAM2%, PARAM3$, PARAM4#, PARAM5#, PARAM6#, PARAM7%=0) None

Party

Function Signature Gate
PARTYMEMBER PARTYMEMBER(PARAM1%, PARAM2%) : Int None

Player

Function Signature Gate
PLAYERACCOUNTEMAIL PLAYERACCOUNTEMAIL(PARAM%) : String None
PLAYERACCOUNTNAME PLAYERACCOUNTNAME(PARAM%) : String None
PLAYERINGAME PLAYERINGAME(PARAM1%) : Int None
PLAYERISBANNED PLAYERISBANNED(PARAM%) : Int None
PLAYERISDM PLAYERISDM(PARAM%) : Int None
PLAYERISGM PLAYERISGM(PARAM%) : Int None
PLAYERSINZONE PLAYERSINZONE(PARAM1$, INSTANCE%=0) : Int None

Attributes

Function Signature Gate
ATTRIBUTE ATTRIBUTE(PARAM1%, PARAM2$) : Int None
CHANGEATTRIBUTE CHANGEATTRIBUTE(PARAM1%, PARAM2$, PARAM3%) Privileged
SETATTRIBUTE SETATTRIBUTE(PARAM1%, PARAM2$, PARAM3%) Privileged

Currency & Progression

Function Signature Gate
CHANGEGOLD CHANGEGOLD(PARAM1%, PARAM2%) Privileged
CHANGEMONEY CHANGEMONEY(PARAM1%, PARAM2%) Privileged
GIVEXP GIVEXP(PARAM1%, PARAM2%, PARAM3%=0) Privileged
GOLD GOLD(PARAM1%) : Int None
MONEY MONEY(PARAM1%) : Int None
SETGOLD SETGOLD(PARAM1%, PARAM2%) Privileged
SETMONEY SETMONEY(PARAM1%, PARAM2%) Privileged

World / Zone

Function Signature Gate
CREATEZONEINSTANCE CREATEZONEINSTANCE(PARAM1$, INSTANCE%=0) : Int None
REMOVEZONEINSTANCE REMOVEZONEINSTANCE(PARAM1$, INSTANCE%) Privileged
ZONEINSTANCEEXISTS ZONEINSTANCEEXISTS(PARAM1$, INSTANCE%) : Int None
ZONEOUTDOORS ZONEOUTDOORS(PARAM1$) : Int None

Faction

Function Signature Gate
FACTIONRATING FACTIONRATING(PARAM1%, PARAM2$) : Int None

Quest

Function Signature Gate
QUESTCOMPLETE QUESTCOMPLETE(PARAM1%, PARAM2$) : Int None
QUESTSTATUS QUESTSTATUS(PARAM1%, PARAM2$) : String None

Trade & Inventory

Function Signature Gate
OPENTRADING OPENTRADING(PARAM1%, PARAM2%) None

Chat & Effects

Function Signature Gate
CREATEFLOATINGNUMBER CREATEFLOATINGNUMBER(PARAM1%, PARAM2%, PARAM3%=255, PARAM4%=255, PARAM5%=255) None

Script Control

Function Signature Gate
REFRESHSCRIPTS REFRESHSCRIPTS() Privileged
THREADEXECUTE THREADEXECUTE(NAME$, FUNC$, ACTOR%=0, CONTEXTACTOR%=0, PARAM$ = "") None

Globals

Function Signature Gate
SUPERGLOBAL SUPERGLOBAL(PARAM1%) : String None

Networking

Function Signature Gate
CREATEUDPSTREAM CREATEUDPSTREAM(Param1%=0) : Int Privileged
RECVUDPMSG RECVUDPMSG(Param1%) : String Privileged
SENDUDPMSG SENDUDPMSG(Param1%, Param2%, Param3%) Privileged
UDPMSGIP UDPMSGIP(Param1%) : Int Privileged
UDPMSGPORT UDPMSGPORT(Param1%) : Int Privileged
UDPSTREAMIP UDPSTREAMIP(Param1%) : Int Privileged
UDPSTREAMPORT UDPSTREAMPORT(Param1%) : Int Privileged
UDPTIMEOUTS UDPTIMEOUTS(Param1%) Privileged

I/O & Persistence

Function Signature Gate
APPENDFILE APPENDFILE(PARAM1$) : Int Privileged
CREATEDIR CREATEDIR(PARAM1$) : Int Privileged
DELETEFILE DELETEFILE(PARAM1$) Privileged
FILESIZE FILESIZE(PARAM1$) : Int None
FILETYPE FILETYPE(PARAM1$) : Int None
MYSQLFETCHROW MYSQLFETCHROW(PARAM1%) : String Privileged
MYSQLFREEQUERY MYSQLFREEQUERY(PARAM1%) Privileged
MYSQLFREEROW MYSQLFREEROW(PARAM1%) Privileged
MYSQLGETVAR MYSQLGETVAR(PARAM1%,PARAM2$) : String Privileged
MYSQLNUMROWS MYSQLNUMROWS(PARAM1%) : Int Privileged
MYSQLQUERY MYSQLQUERY(PARAM1$) : String Privileged
OPENFILE OPENFILE(PARAM1$) : Int Privileged
READFILE READFILE(PARAM1$) : Int None
WRITEFILE WRITEFILE(PARAM1$) : Int Privileged

Diagnostic

Function Signature Gate
RUNTIMEERROR RUNTIMEERROR(PARAM1$="") Privileged

Misc

Function Signature Gate
ABILITYKNOWN ABILITYKNOWN(PARAM1%, PARAM2$) : Int None
ABILITYLEVEL ABILITYLEVEL(PARAM1%, PARAM2$) : Int None
ABILITYMEMORISED ABILITYMEMORISED(PARAM1%, PARAM2$) : Int None
ADDABILITY ADDABILITY(PARAM1%, PARAM2$, PARAM3%=1) None
ADDACTOREFFECT ADDACTOREFFECT(PARAM1%, PARAM2$, PARAM3$, PARAM4%, PARAM5%, PARAM6%) None
ANIMATEACTOR ANIMATEACTOR(PARAM1%, PARAM2$, PARAM3#, PARAM4%=0) None
ARMOURLEVEL ARMOURLEVEL(Param1%) : Int None
BACKPACKCOUNT BACKPACKCOUNT(Param1%, Param2%) : Int None
BANPLAYER BANPLAYER(PARAM%) Privileged
BUBBLEOUTPUT BUBBLEOUTPUT(PARAM1%, PARAM2$, PARAM3%=255, PARAM4%=255, PARAM5%=255) None
CHANGEACTOR CHANGEACTOR(PARAM1%, PARAM2%) Privileged
CHANGEFACTIONRATING CHANGEFACTIONRATING(PARAM1%, PARAM2$, PARAM3%) Privileged
CHANGEMAXATTRIBUTE CHANGEMAXATTRIBUTE(PARAM1%, PARAM2$, PARAM3%) Privileged
CLASS CLASS(PARAM1%) : String None
CLOSEUDPSTREAM CLOSEUDPSTREAM(Param1%) Privileged
COMPLETEQUEST COMPLETEQUEST(PARAM1%, PARAM2$) None
CONTEXTACTOR CONTEXTACTOR() : Int None
COUNTHOSTIPS COUNTHOSTIPS(Param1%) : Int Privileged
COUNTPARTYMEMBERS COUNTPARTYMEMBERS(PARAM%) : Int None
CREATEEMITTER CREATEEMITTER(PARAM1%, PARAM2$, PARAM3%, PARAM4%, PARAM5#=0, PARAM6#=0, PARAM7#=0, PARAM8%=0) None
DAY DAY() : Int None
DEFAULTFACTIONRATING DEFAULTFACTIONRATING(PARAM1$, PARAM2$) : Int None
DELETEABILITY DELETEABILITY(PARAM1%, PARAM2$) None
DELETEACTOREFFECT DELETEACTOREFFECT(PARAM1%, PARAM2$) None
DELETEQUEST DELETEQUEST(PARAM1%, PARAM2$) None
DEQUOTE DEQUOTE(PARAM1$) : String None
DOTTEDIP DOTTEDIP(Param1%) : String Privileged
FINDACTOR FINDACTOR(PARAM1$, ACTORTYPE% = 3) : Int None
FIREPROJECTILE FIREPROJECTILE(PARAM1%, PARAM2%, PARAM3$) SelfOrPrivileged
FIRSTACTORINZONE FIRSTACTORINZONE(PARAM1$, PARAM2%=0) : Int None
FULLTRIM FULLTRIM(PARAM1$) : String None
GETFACTION GETFACTION(Param1%) : String None
GETRNID GETRNID(PARAM1%) : Int None
GETRUNTIMEID GETRUNTIMEID(PARAM1%) : Int None
GETWAITRESULT GETWAITRESULT() : String None
GIVEKILLXP GIVEKILLXP(PARAM1%, PARAM2%) Privileged
GOTO GOTO(PARAM$) None
GOTOIF GOTOIF(PARAM$) None
HASITEM HASITEM(PARAM1%, PARAM2$, PARAM3%=1) : Int None
HOMEFACTION HOMEFACTION(PARAM1%) : String None
HOSTIP HOSTIP(Param1%) : Int Privileged
HOUR HOUR() : Int None
KICKPLAYER KICKPLAYER(Param%) Privileged
KILLACTOR KILLACTOR(PARAM1%, PARAM2%=0) Privileged
MAXATTRIBUTE MAXATTRIBUTE(PARAM1%, PARAM2$) : Int None
MINUTE MINUTE() : Int None
MOD MOD(PARAM1#, PARAM2#) : Float None
MONTH MONTH() : String None
NAME NAME(PARAM1%) : String None
NEWQUEST NEWQUEST(PARAM1%, PARAM2$, PARAM3$, PARAM4%=255, PARAM5%=255, PARAM6%=255) None
NEXTACTOR NEXTACTOR(PARAM1%=0) : Int None
NEXTACTORINZONE NEXTACTORINZONE(PARAM1%) : Int None
OUTPUT OUTPUT(PARAM1%, PARAM2$, PARAM3%=255, PARAM4%=255, PARAM5%=255) None
PARAMETER PARAMETER(PARAM1%) : String None
PERSISTENT PERSISTENT(Param1%) None
PLAYMUSIC PLAYMUSIC(PARAM1%, PARAM2%, PARAM3%=0) None
PLAYSOUND PLAYSOUND(PARAM1%, PARAM2%, PARAM3%=0) None
PLAYSPEECH PLAYSPEECH(PARAM1%, PARAM2%=0) None
RACE RACE(PARAM1%) : String None
REPUTATION REPUTATION(PARAM1%) : Int None
RESISTANCE RESISTANCE(PARAM1%, PARAM2$) : Int None
SAVESTATE SAVESTATE() Privileged
SCENERYOWNER SCENERYOWNER(PARAM1$, PARAM2%, PARAM3%=0) : Int Dead
SCREENFLASH SCREENFLASH(PARAM1%, PARAM2%, PARAM3%, PARAM4%, PARAM5%, PARAM6%, PARAM7%=0) None
SCRIPTLOG SCRIPTLOG(PARAM1$="") None
SEASON SEASON() : String None
SETABILITYLEVEL SETABILITYLEVEL(PARAM1%, PARAM2$, PARAM3%) Privileged
SETFACTIONRATING SETFACTIONRATING(PARAM1%, PARAM2$, PARAM3%) Privileged
SETHOMEFACTION SETHOMEFACTION(PARAM1%, PARAM2$) Privileged
SETLEADER SETLEADER(PARAM1%, PARAM2%) Privileged
SETMAXATTRIBUTE SETMAXATTRIBUTE(PARAM1%, PARAM2$, PARAM3%) Privileged
SETNAME SETNAME(PARAM1%, PARAM2$) Privileged
SETOWNER SETOWNER(PARAM1%, PARAM2$, PARAM3%, PARAM4% = 0) Dead
SETREPUTATION SETREPUTATION(PARAM1%, PARAM2%) Privileged
SETRESISTANCE SETRESISTANCE(PARAM1%, PARAM2$, PARAM3%) Privileged
SETSUPERGLOBAL SETSUPERGLOBAL(PARAM1%, PARAM2$) None
SETTAG SETTAG(PARAM1%, PARAM2$) Privileged
SETWAITINFO SETWAITINFO(PARAM1%, PARAM2%) None
SETWAITING SETWAITING(X%) None
SETWAITITEM SETWAITITEM(PARAM1%, PARAM2$, PARAM3%) None
SETWAITKILL SETWAITKILL(PARAM1%, PARAM2%, PARAM3%) None
SETWAITSPEAK SETWAITSPEAK(PARAM1%, PARAM2%) None
SETWAITSTART SETWAITSTART(PARAM1%) None
SETWAITTIME SETWAITTIME(PARAM1%) None
SPLIT SPLIT(PARAM1$, PARAM2%, PARAM3$=",") : String None
SQLACCOUNTID SQLACCOUNTID(PARAM1%) : Int None
SQLACTORID SQLACTORID(PARAM1%) : Int None
TAG TAG(PARAM1%) : String None
UPDATEQUEST UPDATEQUEST(PARAM1%, PARAM2$, PARAM3$, PARAM4%=255, PARAM5%=255, PARAM6%=255) None
UPDATEXPBAR UPDATEXPBAR(PARAM1%, PARAM2%) None
WARP WARP(PARAM1%, PARAM2$, PARAM3$, PARAM4%=0) Privileged
YEAR YEAR() : Int None

See also