Skip to content

Lua Scripting

Jump to bottom
REghZy edited this page Oct 8, 2025 · 36 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.

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 formatted as hex ('0x' prefix is not required).

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.

Note

Remote procedure calls are not currently in the v1.1.8 release, only in the debug builds

Function Arguments

These functions will have an argarray argument at the end of the function. An argarray is a table containing tables, and those tables must contain two array elements:

  • Type (string)
  • Value (any, based on the type)

The available value types are: byte, int, ulong, float, byte[], int[], ulong[], float[] and string.

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

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"})

Example Usages

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

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

Available Functions

  • callvoidat(address : number|string, args : argarray)
  • callvoidin(module : string, ordinal : number|string, args : argarray)

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