Skip to main content

SynSaveInstance

Represents the options for saving instances with custom settings using the synsaveinstance function.

Types​

CustomOptions table​

</>
interface CustomOptions table {
__DEBUG_MODE: boolean--

Recommended to enable if you wish to help us improve our products and find bugs / issues with it! Default: false

ReadMe: boolean--

Default: true

SafeMode: boolean--

Kicks you before Saving, which prevents you from being detected in any game. Default: false

ShutdownWhenDone: boolean--

Shuts the game down after saveinstance is finished. Default: false

AntiIdle: boolean--

Prevents the 20-minute-Idle Kick. Default: true

Anonymous: boolean--
  • RISKY: Cleans the file of any info related to your account like: Name, UserId. This is useful for some games that might store that info in GUIs or other Instances. Might potentially mess up parts of strings that contain characters that match your Name or parts of numbers that match your UserId. Default: false
ShowStatus: boolean--

Default: true

Callback: boolean--

If set, the serialized data will be sent to the callback function instead of to file. Default: nil

mode: string--

Change this to invalid mode like "invalid" if you only want ExtraInstances. "optimized" mode is NOT supported with @Object option. Default: "optimized"

noscripts: boolean--

Aliases: Decompile. Default: false

scriptcache: boolean--

Default: true

decomptype: string--
  • "custom" - for built-in custom decompiler. Default: Your executor's decompiler, if available. Otherwise uses "custom" if not.
timeout: number--

If the decompilation run time exceeds this value it gets cancelled. Set to -1 to disable timeout (unreliable). Aliases: DecompileTimeout. Default: 10

DecompileJobless: boolean--

Includes already decompiled code in the output. No new scripts are decompiled. Default: false

SaveBytecode: boolean--

Includes bytecode in the output. Useful if you wish to be able to decompile it yourself later. Default: false

DecompileIgnore: {Instance | Instance.ClassName | [Instance.ClassName]={Instance.Name}}--
  • Ignores match & it's descendants by default. To Ignore only the instance itself set the value to = false. Examples: "Chat", - Matches any instance with "Chat" ClassName, Players = {"MyPlayerName"} - Matches "Players" Class AND "MyPlayerName" Name ONLY, workspace - matches Instance by reference, [workspace] = false - matches Instance by reference and only ignores the instance itself and not it's descendants. Default: {Chat, TextChatService}
IgnoreList: {Instance | Instance.ClassName | [Instance.ClassName]={Instance.Name}}--

Structure is similar to @DecompileIgnore except = false meaning if you ignore one instance it will automatically ignore it's descendants. Default: {CoreGui, CorePackages}

ExtraInstances: {Instance}--

If used with any invalid mode (like "invalidmode") it will only save these instances. Default: {}

IgnoreProperties: table--

Ignores properties by Name. Default: {}

SaveCacheInterval: number--

The less the value the more often it saves, but that would mean less performance due to constantly saving. Default: 0x1600 * 10

FilePath: string--

Must only contain the name of the file, no file extension. Default: false

Object: Instance--
  • If provided, saves as .rbxmx (Model file) instead. If Object is game, it will be saved as a .rbxl file. MUST BE AN INSTANCE REFERENCE, FOR EXAMPLE - game.Workspace. "optimized" mode is NOT supported with this option. If IsModel is set to false then Object specified here will be saved as a place file. Only saves the instance itself, not the descendants. If you wish to save descendants too then use @ExtraInstances={Object}. Default: false
IsModel: boolean--

If Object is specified then sets to true automatically, unless you set it to false. Default: false

NilInstances: boolean--

Save instances that aren't Parented (Parented to nil). Default: false

NilInstancesFixes: {[Instance.ClassName]=function}--
  • This can cause some Classes to be fixed even though they might not need the fix (better be safe than sorry though). For example, Bones inherit from Attachment if we dont define them in the NilInstancesFixes then this will catch them anyways. TO AVOID THIS BEHAVIOR USE THIS EXAMPLE: {ClassName_That_Doesnt_Need_Fix = false}. Default: {Animator = function, AdPortal = function, BaseWrap = function, Attachment = function}
IgnoreDefaultProperties: boolean--

Ignores default properties during saving. Default: true

IgnoreNotArchivable: boolean--

Ignores the Archivable property and saves Non-Archivable instances. Default: true

IgnorePropertiesOfNotScriptsOnScriptsMode: boolean--

Ignores property of every instance that is not a script in "scripts" mode. Default: false

IgnoreSpecialProperties: boolean--

Prevents calls to gethiddenproperty and uses fallback methods instead. This also helps with crashes. If your file is corrupted after saving, you can try turning this on. Default: false

IsolateLocalPlayer: boolean--

Saves Children of LocalPlayer as separate folder and prevents any instance of ClassName Player with .Name identical to LocalPlayer.Name from saving. Default: false

IsolateStarterPlayer: boolean--

If enabled, StarterPlayer will be cleared and the saved starter player will be placed into folders. Default: false

IsolateLocalPlayerCharacter: boolean--

Saves Children of LocalPlayer.Character as separate folder and prevents any instance of ClassName Player with .Name identical to LocalPlayer.Name from saving. Default: false

RemovePlayerCharacters: boolean--

Ignore player characters while saving. (Enables SaveNonCreatable automatically). Default: true

SaveNonCreatable: boolean--
  • Includes non-serializable instances as Folder objects (Name is misleading as this is mostly a fix for certain NilInstances and isn't always related to NotCreatable). Default: false
NotCreatableFixes: table<Instance.ClassName>--
  • {"Player"} is the same as {Player = "Folder"}; Format like {SpawnLocation = "Part"} is only to be used when SpawnLocation inherits from "Part" AND "Part" is Creatable. Default: { "Player", "PlayerScripts", "PlayerGui" }
IsolatePlayers: boolean--
AlternativeWritefile: boolean--
  • Uses breaks down file content string into segments and writes them using appendfile. This might help with crashes when it starts writing to file. Default: true
IgnoreDefaultPlayerScripts: boolean--
  • **RISKY: Ignores Default PlayerScripts like PlayerModule & RbxCharacterSounds. Prevents crashes on certain Executors. Default: true
IgnoreSharedStrings: boolean--
  • RISKY: FIXES CRASHES (TEMPORARY, TESTED ON ROEXEC ONLY). FEEL FREE TO DISABLE THIS TO SEE IF IT WORKS FOR YOU. Default: true
SharedStringOverwrite: boolean--
  • RISKY: if the process is not finished aka crashed then none of the affected values will be available. SharedStrings can also be used for ValueTypes that aren't SharedString, this behavior is not documented anywhere but makes sense (Could create issues though, due to potential ValueType mix-up, only works on certain types which are all base64 encoded so far). Reason: Allows for potential smaller file size (can also be bigger in some cases). Default: false
TreatUnionsAsParts: boolean--
  • RISKY: Converts all UnionOperations to Parts. Useful if your Executor isn't able to save (read) Unions, because otherwise they will be invisible. Default: false (except Solara)
}
  • Structure of the main CustomOptions table.
  • Note: Aliases take priority over parent option name.

OptionsAliases​

</>
interface OptionsAliases {
FilePath: string--

FileName

IgnoreDefaultProperties: string--

IgnoreDefaultProps

SaveNonCreatable: string--

SaveNotCreatable

IsolatePlayers: string--

SavePlayers

scriptcache: string--

DecompileJobless

timeout: string--

DecompileTimeout

IgnoreNotArchivable: string--

IgnoreArchivable

RemovePlayerCharacters: string--

INVERSE SavePlayerCharacters

}

Functions​

saveinstance​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
SynSaveInstance.saveinstance(
Parameter_1: variant<table,table<Instance>>,--

Can either be SynSaveInstance.CustomOptions table or a filled with instances ({Instance}), (then it will be treated as ExtraInstances with an invalid mode and IsModel will be true).

Parameter_2: table--

[OPTIONAL] If present, then Parameter_2 will be assumed to be SynSaveInstance.CustomOptions table. And then if the Parameter_1 is an Instance, then it will be assumed to be SynSaveInstance.CustomOptions table.Object. If Parameter_1 is a table filled with instances ({Instance}), then it will be assumed to be SynSaveInstance.CustomOptions table.ExtraInstances and IsModel will be true). This exists for sake compatibility with saveinstance(game, {})

) → ()

Saves instances with specified options. Example:

local Params = {
	RepoURL = "https://raw.githubusercontent.com/luau/SynSaveInstance/main/",
	SSI = "saveinstance",
}

local synsaveinstance = loadstring(game:HttpGet(Params.RepoURL .. Params.SSI .. ".luau", true), Params.SSI)()

local CustomOptions = { SafeMode = true, timeout = 15, SaveBytecode = true }

synsaveinstance(CustomOptions)
Show raw api
{
    "functions": [
        {
            "name": "saveinstance",
            "desc": "Saves instances with specified options. Example:\n```lua\nlocal Params = {\n\tRepoURL = \"https://raw.githubusercontent.com/luau/SynSaveInstance/main/\",\n\tSSI = \"saveinstance\",\n}\n\nlocal synsaveinstance = loadstring(game:HttpGet(Params.RepoURL .. Params.SSI .. \".luau\", true), Params.SSI)()\n\nlocal CustomOptions = { SafeMode = true, timeout = 15, SaveBytecode = true }\n\nsynsaveinstance(CustomOptions)\n```",
            "params": [
                {
                    "name": "Parameter_1",
                    "desc": "Can either be [SynSaveInstance.CustomOptions table] or a filled with instances ({Instance}), (then it will be treated as ExtraInstances with an invalid mode and IsModel will be true).",
                    "lua_type": "variant<table, table<Instance>>"
                },
                {
                    "name": "Parameter_2",
                    "desc": "[OPTIONAL] If present, then Parameter_2 will be assumed to be [SynSaveInstance.CustomOptions table]. And then if the Parameter_1 is an Instance, then it will be assumed to be [SynSaveInstance.CustomOptions table].Object. If Parameter_1 is a table filled with instances ({Instance}), then it will be assumed to be [SynSaveInstance.CustomOptions table].ExtraInstances and IsModel will be true). This exists for sake compatibility with `saveinstance(game, {})`",
                    "lua_type": "table"
                }
            ],
            "returns": [],
            "function_type": "static",
            "yields": true,
            "source": {
                "line": 1363,
                "path": "saveinstance.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "CustomOptions table",
            "desc": "* Structure of the main CustomOptions table.\n* Note: Aliases take priority over parent option name.",
            "fields": [
                {
                    "name": "__DEBUG_MODE",
                    "lua_type": "boolean",
                    "desc": "Recommended to enable if you wish to help us improve our products and find bugs / issues with it! ___Default:___ false"
                },
                {
                    "name": "ReadMe",
                    "lua_type": "boolean",
                    "desc": "___Default:___ true"
                },
                {
                    "name": "SafeMode",
                    "lua_type": "boolean",
                    "desc": "Kicks you before Saving, which prevents you from being detected in any game. ___Default:___ false"
                },
                {
                    "name": "ShutdownWhenDone",
                    "lua_type": "boolean",
                    "desc": "Shuts the game down after saveinstance is finished. ___Default:___ false"
                },
                {
                    "name": "AntiIdle",
                    "lua_type": "boolean",
                    "desc": "Prevents the 20-minute-Idle Kick. ___Default:___ true"
                },
                {
                    "name": "Anonymous",
                    "lua_type": "boolean",
                    "desc": "* **RISKY:** Cleans the file of any info related to your account like: Name, UserId. This is useful for some games that might store that info in GUIs or other Instances. Might potentially mess up parts of strings that contain characters that match your Name or parts of numbers that match your UserId. ___Default:___ false"
                },
                {
                    "name": "ShowStatus",
                    "lua_type": "boolean",
                    "desc": "___Default:___ true"
                },
                {
                    "name": "Callback",
                    "lua_type": "boolean",
                    "desc": "If set, the serialized data will be sent to the callback function instead of to file. ___Default:___ nil"
                },
                {
                    "name": "mode",
                    "lua_type": "string",
                    "desc": "Change this to invalid mode like \"invalid\" if you only want ExtraInstances. \"optimized\" mode is **NOT** supported with *@Object* option. ___Default:___ `\"optimized\"`"
                },
                {
                    "name": "noscripts",
                    "lua_type": "boolean",
                    "desc": "___Aliases:___ `Decompile`. ___Default:___ false"
                },
                {
                    "name": "scriptcache",
                    "lua_type": "boolean",
                    "desc": "___Default:___ true"
                },
                {
                    "name": "decomptype",
                    "lua_type": "string",
                    "desc": "* \"custom\" - for built-in custom decompiler. ___Default:___ Your executor's decompiler, if available. Otherwise uses \"custom\" if not."
                },
                {
                    "name": "timeout",
                    "lua_type": "number",
                    "desc": "If the decompilation run time exceeds this value it gets cancelled. Set to -1 to disable timeout (unreliable). ***Aliases***: `DecompileTimeout`. ___Default:___ 10"
                },
                {
                    "name": "DecompileJobless",
                    "lua_type": "boolean",
                    "desc": "Includes already decompiled code in the output. No new scripts are decompiled. ___Default:___ false"
                },
                {
                    "name": "SaveBytecode",
                    "lua_type": "boolean",
                    "desc": "Includes bytecode in the output. Useful if you wish to be able to decompile it yourself later. ___Default:___ false"
                },
                {
                    "name": "DecompileIgnore",
                    "lua_type": "{Instance | Instance.ClassName | [Instance.ClassName] = {Instance.Name}}",
                    "desc": "* Ignores match & it's descendants by default. To Ignore only the instance itself set the value to `= false`. Examples: \"Chat\", - Matches any instance with \"Chat\" ClassName, Players = {\"MyPlayerName\"} - Matches \"Players\" Class AND \"MyPlayerName\" Name ONLY, `workspace` - matches Instance by reference, `[workspace] = false` - matches Instance by reference and only ignores the instance itself and not it's descendants. ___Default:___ {Chat, TextChatService}"
                },
                {
                    "name": "IgnoreList",
                    "lua_type": "{Instance | Instance.ClassName | [Instance.ClassName] = {Instance.Name}}",
                    "desc": "Structure is similar to **@DecompileIgnore** except `= false` meaning if you ignore one instance it will automatically ignore it's descendants. ___Default:___ {CoreGui, CorePackages}"
                },
                {
                    "name": "ExtraInstances",
                    "lua_type": "{Instance}",
                    "desc": "If used with any invalid mode (like \"invalidmode\") it will only save these instances. ___Default:___ {}"
                },
                {
                    "name": "IgnoreProperties",
                    "lua_type": "table",
                    "desc": "Ignores properties by Name. ___Default:___ {}"
                },
                {
                    "name": "SaveCacheInterval",
                    "lua_type": "number",
                    "desc": "The less the value the more often it saves, but that would mean less performance due to constantly saving. ___Default:___ 0x1600 * 10"
                },
                {
                    "name": "FilePath",
                    "lua_type": "string",
                    "desc": "Must only contain the name of the file, no file extension. ___Default:___ false"
                },
                {
                    "name": "Object",
                    "lua_type": "Instance",
                    "desc": "* If provided, saves as .rbxmx (Model file) instead. If Object is game, it will be saved as a .rbxl file. **MUST BE AN INSTANCE REFERENCE, FOR EXAMPLE - *game.Workspace***. `\"optimized\"` mode is **NOT** supported with this option. If IsModel is set to false then Object specified here will be saved as a place file. Only saves the instance itself, not the descendants. If you wish to save descendants too then use @ExtraInstances={Object}. ___Default:___ false"
                },
                {
                    "name": "IsModel",
                    "lua_type": "boolean",
                    "desc": "If Object is specified then sets to true automatically, unless you set it to false. ___Default:___ false"
                },
                {
                    "name": "NilInstances",
                    "lua_type": "boolean",
                    "desc": "Save instances that aren't Parented (Parented to nil). ___Default:___ false"
                },
                {
                    "name": "NilInstancesFixes",
                    "lua_type": "{[Instance.ClassName] = function}",
                    "desc": "* This can cause some Classes to be fixed even though they might not need the fix (better be safe than sorry though). For example, Bones inherit from Attachment if we dont define them in the NilInstancesFixes then this will catch them anyways. **TO AVOID THIS BEHAVIOR USE THIS EXAMPLE:** {ClassName_That_Doesnt_Need_Fix = false}. ___Default:___ {Animator = function, AdPortal = function, BaseWrap = function, Attachment = function}"
                },
                {
                    "name": "IgnoreDefaultProperties",
                    "lua_type": "boolean",
                    "desc": "Ignores default properties during saving.  ___Default:___ true"
                },
                {
                    "name": "IgnoreNotArchivable",
                    "lua_type": "boolean",
                    "desc": "Ignores the Archivable property and saves Non-Archivable instances. ___Default:___ true"
                },
                {
                    "name": "IgnorePropertiesOfNotScriptsOnScriptsMode",
                    "lua_type": "boolean",
                    "desc": "Ignores property of every instance that is not a script in \"scripts\" mode. ___Default:___ false"
                },
                {
                    "name": "IgnoreSpecialProperties",
                    "lua_type": "boolean",
                    "desc": "Prevents calls to `gethiddenproperty` and uses fallback methods instead. This also helps with crashes. If your file is corrupted after saving, you can try turning this on. ___Default:___ false"
                },
                {
                    "name": "IsolateLocalPlayer",
                    "lua_type": "boolean",
                    "desc": "Saves Children of LocalPlayer as separate folder and prevents any instance of ClassName Player with .Name identical to LocalPlayer.Name from saving. ___Default:___ false"
                },
                {
                    "name": "IsolateStarterPlayer",
                    "lua_type": "boolean",
                    "desc": "If enabled, StarterPlayer will be cleared and the saved starter player will be placed into folders. ___Default:___ false"
                },
                {
                    "name": "IsolateLocalPlayerCharacter",
                    "lua_type": "boolean",
                    "desc": "Saves Children of LocalPlayer.Character as separate folder and prevents any instance of ClassName Player with .Name identical to LocalPlayer.Name from saving. ___Default:___ false"
                },
                {
                    "name": "RemovePlayerCharacters",
                    "lua_type": "boolean",
                    "desc": "Ignore player characters while saving. (Enables SaveNonCreatable automatically). ___Default:___ true"
                },
                {
                    "name": "SaveNonCreatable",
                    "lua_type": "boolean",
                    "desc": "* Includes non-serializable instances as Folder objects (Name is misleading as this is mostly a fix for certain NilInstances and isn't always related to NotCreatable). ___Default:___ false"
                },
                {
                    "name": "NotCreatableFixes",
                    "lua_type": "table<Instance.ClassName>",
                    "desc": "* {\"Player\"} is the same as {Player = \"Folder\"}; Format like {SpawnLocation = \"Part\"} is only to be used when SpawnLocation inherits from \"Part\" AND \"Part\" is Creatable. ___Default:___ { \"Player\", \"PlayerScripts\", \"PlayerGui\" }"
                },
                {
                    "name": "IsolatePlayers",
                    "lua_type": "boolean",
                    "desc": "* This option does save players, it's just they won't show up in Studio and can only be viewed through the place file code (in text editor). More info at https://github.com/luau/UniversalSynSaveInstance/issues/2. ___Default:___ false"
                },
                {
                    "name": "AlternativeWritefile",
                    "lua_type": "boolean",
                    "desc": "* Uses breaks down file content string into segments and writes them using appendfile. This might help with crashes when it starts writing to file. ___Default:___ true"
                },
                {
                    "name": "IgnoreDefaultPlayerScripts",
                    "lua_type": "boolean",
                    "desc": "* **RISKY: Ignores Default PlayerScripts like PlayerModule & RbxCharacterSounds. Prevents crashes on certain Executors. ___Default:___ true"
                },
                {
                    "name": "IgnoreSharedStrings",
                    "lua_type": "boolean",
                    "desc": "* **RISKY: FIXES CRASHES (TEMPORARY, TESTED ON ROEXEC ONLY). FEEL FREE TO DISABLE THIS TO SEE IF IT WORKS FOR YOU**. ___Default:___ true"
                },
                {
                    "name": "SharedStringOverwrite",
                    "lua_type": "boolean",
                    "desc": "* **RISKY:** if the process is not finished aka crashed then none of the affected values will be available. SharedStrings can also be used for ValueTypes that aren't `SharedString`, this behavior is not documented anywhere but makes sense (Could create issues though, due to _potential_ ValueType mix-up, only works on certain types which are all base64 encoded so far). Reason: Allows for potential smaller file size (can also be bigger in some cases). ___Default:___ false"
                },
                {
                    "name": "TreatUnionsAsParts",
                    "lua_type": "boolean",
                    "desc": "* **RISKY:** Converts all UnionOperations to Parts. Useful if your Executor isn't able to save (read) Unions, because otherwise they will be invisible. ___Default:___ false (except Solara)"
                }
            ],
            "source": {
                "line": 1330,
                "path": "saveinstance.luau"
            }
        },
        {
            "name": "OptionsAliases",
            "desc": "Aliases for the [SynSaveInstance.CustomOptions table].",
            "fields": [
                {
                    "name": "FilePath",
                    "lua_type": "string",
                    "desc": "FileName"
                },
                {
                    "name": "IgnoreDefaultProperties",
                    "lua_type": "string",
                    "desc": "IgnoreDefaultProps"
                },
                {
                    "name": "SaveNonCreatable",
                    "lua_type": "string",
                    "desc": "SaveNotCreatable"
                },
                {
                    "name": "IsolatePlayers",
                    "lua_type": "string",
                    "desc": "SavePlayers"
                },
                {
                    "name": "scriptcache",
                    "lua_type": "string",
                    "desc": "DecompileJobless"
                },
                {
                    "name": "timeout",
                    "lua_type": "string",
                    "desc": "DecompileTimeout"
                },
                {
                    "name": "IgnoreNotArchivable",
                    "lua_type": "string",
                    "desc": "IgnoreArchivable"
                },
                {
                    "name": "RemovePlayerCharacters",
                    "lua_type": "string",
                    "desc": "INVERSE SavePlayerCharacters"
                }
            ],
            "source": {
                "line": 1342,
                "path": "saveinstance.luau"
            }
        }
    ],
    "name": "SynSaveInstance",
    "desc": "Represents the options for saving instances with custom settings using the synsaveinstance function.",
    "source": {
        "line": 1284,
        "path": "saveinstance.luau"
    }
}