Skip to content

Lua Scripting

Jump to bottom
REghZy edited this page Oct 17, 2025 · 17 revisions

Accessible in the tools menu (Tools > Scripting), this is an alternative to the Task Sequencer for those who prefer coding rather than visual programming.

Example

Connection

Scripts will use the engine's connection by default. However, like task sequences, each script can have its own dedicated connection. Click the 3rd button on the bottom-left of the screen to open the connection dialog, or right-click the tab and click Connect to Console.

Example "tree"

function isdirectory(path)
    return path:sub(-1) == "\\"
end

function printchildren(filePath, prefix)
    local tab = engine.getfiles(filePath, true, true)
    for i, val in pairs(tab) do
        print(prefix .. val)
        if (isdirectory(val)) then
            printchildren(filePath .. val, prefix .. "  ")
        end
    end    
end

local myDrives = engine.drivelist()
for i, drive in pairs(myDrives) do
    print(drive)
    printchildren(drive, "  ")
end

Engine Functions

The engine table contains the functions for network operations. The list of available methods:

  • readnumber(address : string|number, type : string) : number

  • writenumber(address : string|number, type : string, value : number)

  • readstring(address : string|number, length : number) : string

  • writestring(address : string|number, value : string)

  • setfrozen(freeze : boolean) : boolean

    The return value is whether the frozen state was changed. E.g. if already frozen, it returns false.

    local didFreeze = engine.setfrozen(true)
local didUnFreeze = engine.setfrozen(false)

  • isfrozen() : boolean

  • sendnotification(icon : string, message : string?)

    The XNotifyLogo Types section contains a list of available logo types. The message is optional, and some icons do not use the message.

    engine.sendnotification("GAMERTAG_SENT_YOU_A_MESSAGE", "CooLGamer")

  • drivelist() : array[name] (as in, returns an "array" table containing each drive name)

    local things = engine.drivelist()
for i, drive in pairs(things) do
    print(drive)
end

  • getfiles(path : string, includeFiles : boolean, includeDirs : boolean) : array[name]

    Returns an "array" table of files and folders, where each value in the table is the name (relative to the given path).

    Directories end with the path separator char (which is \ on xbox). You can use engine.pathseparator() to find out what it is.

    The parameters includeFiles and includeDirs specify whether to include files and directories in the results. Setting both to false will yield no results.

  • deleterecursive(path : string)

  • launchfile(path : string)

  • movefile(oldPath : string, newPath : string)

  • mkdir(dirPath : string)

  • pathseparator() : string

Functions that take an address must be either a number or a string. For strings, prefix with "0x" to parse as hexadecimal.

Functions that take a number-based data type must be one of byte, short, int, long, float or double.

All of these functions will produce an error if not connected to a console.

Coroutines

These are not currently enabled, because LuaCSharp (the library used for lua scripting) does not appear to use native threads for each coroutine, but instead switches between them. And having tested them, there seems to be a bug with them never stopping, so they are disabled for now.

And also, any network operation (i.e. reading or writing values, reading from file system, etc.) requires obtaining a lock (BusyLock token) on the connection so that no other thread may access it during that operation. This makes coroutines practically useless for scripts trying to do things with the console.

JRPC

When JRPC2 is installed on your console, these functions allow you to make remote calls. Be really careful with what you do, of course. This is still a WIP, so testing and bug reports would be appreciated.

The functions are accessible via the jrpc global table.

Function Arguments

These functions accept arguments in the forms of a "tuple" table, which is an array of two elements:

  • Type (string). One of: byte, int, ulong, float, byte[], int[], ulong[], float[] and string
  • Value (any, based on the type)

Array values are strings with comma-separated values, e.g. an int array argument could be {"int[]", "0,1,32,0x40"}.

Return value "rcptype"

This is used for function calls with return values. Supported values:

  • byte
  • int
  • ulong
  • float
  • byte[length] e.g. byte[4]
  • int[length] e.g. int[4]
  • ulong[length] e.g. ulong[4]
  • float[length] e.g. float[4]
  • string

Note

Integer values represented by strings (including in arrays, since they must be strings), are parsed as decimal by default. Prefix with "0x" to parse as hexadecimal.

Example arguments:

callvoidat("0x12345678", {"byte", "0"}, {"byte", "0x40"})
callvoidat("0x12345678", {"string", "hello!"}, {"int", 24}, {"int[]", "0x89502234,0x2455003D"})
callvoidat("0x12345678", {"string", ""}, {"int", 24}, {"byte[]", "0xFF,255"})
-- UNTESTED!
local text = callin("string", "MyCoolModule", "0x20", {"int", 24}, {"byte[]", "0xFF,255,127,0x7F"})
local myArrayTableWithLen32 = callat("byte[32]", "0x80004000", {"int[]", "24,0x7fffffff"})

Example Usages

MW3 (TU23) void SV_SetConfigString(int index, string value) 

jrpc.callvoidat("0x822CB3E8", {"int", "0x3FA"}, {"string", "rank_prestige10"})

Available Functions

jrpc.getprocaddress(module : string, ordinal : number|string)

jrpc.callvoidat(address : number|string, args...)
jrpc.callvoidat_vm(address : number|string, args...)
jrpc.callvoidat_sys(address : number|string, args...)
jrpc.callvoidat_vm_sys(address : number|string, args...)

jrpc.callat(returnType : rcptype, address : number|string, args...)
jrpc.callat_vm(returnType : rcptype, address : number|string, args...)
jrpc.callat_sys(returnType : rcptype, address : number|string, args...)
jrpc.callat_vm_sys(returnType : rcptype, address : number|string, args...)

jrpc.callvoidin(module : string, ordinal : number|string, args...)
jrpc.callvoidin_vm(module : string, ordinal : number|string, args...)
jrpc.callvoidin_sys(module : string, ordinal : number|string, args...)
jrpc.callvoidin_vm_sys(module : string, ordinal : number|string, args...)

jrpc.callin(returnType : rcptype, module : string, ordinal : number|string, args...)
jrpc.callin_vm(returnType : rcptype, module : string, ordinal : number|string, args...)
jrpc.callin_sys(returnType : rcptype, module : string, ordinal : number|string, args...)
jrpc.callin_vm_sys(returnType : rcptype, module : string, ordinal : number|string, args...)

For more info on rpctype, see RPCType

XNotifyLogo Types

For notifications, this is a list of supported icon types (XNotifyLogo):

  • XBOX_LOGO
  • NEW_MESSAGE_LOGO
  • FRIEND_REQUEST_LOGO
  • NEW_MESSAGE
  • FLASHING_XBOX_LOGO
  • GAMERTAG_SENT_YOU_A_MESSAGE
  • GAMERTAG_SINGED_OUT
  • GAMERTAG_SIGNEDIN
  • GAMERTAG_SIGNED_INTO_XBOX_LIVE
  • GAMERTAG_SIGNED_IN_OFFLINE
  • GAMERTAG_WANTS_TO_CHAT
  • DISCONNECTED_FROM_XBOX_LIVE
  • DOWNLOAD
  • FLASHING_MUSIC_SYMBOL
  • FLASHING_HAPPY_FACE
  • FLASHING_FROWNING_FACE
  • FLASHING_DOUBLE_SIDED_HAMMER
  • GAMERTAG_WANTS_TO_CHAT_2
  • PLEASE_REINSERT_MEMORY_UNIT
  • PLEASE_RECONNECT_CONTROLLERM
  • GAMERTAG_HAS_JOINED_CHAT
  • GAMERTAG_HAS_LEFT_CHAT
  • GAME_INVITE_SENT
  • FLASH_LOGO
  • PAGE_SENT_TO
  • FOUR_2
  • FOUR_3
  • ACHIEVEMENT_UNLOCKED
  • FOUR_9
  • GAMERTAG_WANTS_TO_TALK_IN_VIDEO_KINECT
  • VIDEO_CHAT_INVITE_SENT
  • READY_TO_PLAY
  • CANT_DOWNLOAD_X
  • DOWNLOAD_STOPPED_FOR_X
  • FLASHING_XBOX_CONSOLE
  • X_SENT_YOU_A_GAME_MESSAGE
  • DEVICE_FULL
  • FOUR_7
  • FLASHING_CHAT_ICON
  • ACHIEVEMENTS_UNLOCKED
  • X_HAS_SENT_YOU_A_NUDGE
  • MESSENGER_DISCONNECTED
  • BLANK
  • CANT_SIGN_IN_MESSENGER
  • MISSED_MESSENGER_CONVERSATION
  • FAMILY_TIMER_X_TIME_REMAINING
  • DISCONNECTED_XBOX_LIVE_11_MINUTES_REMAINING
  • KINECT_HEALTH_EFFECTS
  • FOUR_5
  • GAMERTAG_WANTS_YOU_TO_JOIN_AN_XBOX_LIVE_PARTY
  • PARTY_INVITE_SENT
  • GAME_INVITE_SENT_TO_XBOX_LIVE_PARTY
  • KICKED_FROM_XBOX_LIVE_PARTY
  • NULLED
  • DISCONNECTED_XBOX_LIVE_PARTY
  • DOWNLOADED
  • CANT_CONNECT_XBL_PARTY
  • GAMERTAG_HAS_JOINED_XBL_PARTY
  • GAMERTAG_HAS_LEFT_XBL_PARTY
  • GAMER_PICTURE_UNLOCKED
  • AVATAR_AWARD_UNLOCKED
  • JOINED_XBL_PARTY
  • PLEASE_REINSERT_USB_STORAGE_DEVICE
  • PLAYER_MUTED
  • PLAYER_UNMUTED
  • FLASHING_CHAT_SYMBOL
  • UPDATING
Clone this wiki locally