Skip to main content

Smapshot

Smapshot allows for dynamic saving and loading of maps.

Types​

TerrainConfig​

</>
interface TerrainConfig {
slice: (BasePart | Region3int16)?--

Region of terrain to save. If a BasePart is provided it is converted to a Region3int16. When nil, all terrain is saved.

}

LightingConfig​

</>
interface LightingConfig {
whitelist: {string}?--

Names of Lighting children (effects, atmospheres, skies) to include. Mutually exclusive with blacklist.

blacklist: {string}?--

Names of Lighting children to exclude.

}

InstanceConfig​

</>
interface InstanceConfig {
instances: {Instance}--

Instances to capture.

saveParents: boolean?--

When true, each instance's original parent path is recorded so it can be restored on load. Defaults to false.

}

WorkspaceConfig​

</>
interface WorkspaceConfig {
whitelist: {string}?--

Names of Workspace children to include. Terrain and CurrentCamera are always skipped here. Mutually exclusive with blacklist.

blacklist: {string}?--

Names of Workspace children to exclude.

saveCameraCFrame: boolean?--

When true, the current Camera.CFrame is captured and restored on load.

}

MusicConfig​

</>
interface MusicConfig {
whitelist: {string}?--

Names of SoundService children to include. Mutually exclusive with blacklist.

blacklist: {string}?--

Names of SoundService children to exclude.

}

MaterialConfig​

</>
interface MaterialConfig {
whitelist: {string}?--

Names of MaterialService children to include. Mutually exclusive with blacklist.

blacklist: {string}?--

Names of MaterialService children to exclude.

materialFilter: {Enum.Material}?--

If provided, only MaterialVariants whose BaseMaterial is in this list are captured.

}

SimpleLoadOverwrite​

</>
interface SimpleLoadOverwrite {
keepDirty: boolean?--

When true, existing state is preserved instead of being cleared before this section is applied. Overrides globalKeepDirty for this section.

consume: boolean?--

When true, the section's children are reparented into the target service instead of cloned, and the section is tagged so it is skipped on subsequent loads. Overrides globalConsume for this section.

ignoreOnLoad: boolean?--

When true, this section is skipped entirely on load.

}

LoadOverwrite​

</>
interface LoadOverwrite {
keepDirty: boolean?--

When true, existing state is preserved instead of being cleared before this section is applied. Overrides globalKeepDirty for this section.

consume: boolean?--

When true, the section's children are reparented into the target service instead of cloned, and the section is tagged so it is skipped on subsequent loads. Overrides globalConsume for this section.

ignoreOnLoad: boolean?--

When true, this section is skipped entirely on load.

ignoreOnClear: {Instance}?--

Instances to leave in place when the target service is cleared (only applies when keepDirty is not set, since that is the only path that clears).

}

LoadConfig​

</>
interface LoadConfig {
globalConsume: boolean?--

Default consume applied to every section that does not set its own. See SimpleLoadOverwrite.

globalKeepDirty: boolean?--

Default keepDirty applied to every section that does not set its own.

globalIgnoreOnClear: {Instance}?--

Default ignoreOnClear applied to every clearing section (Lighting/Workspace/SoundService/MaterialService) that does not set its own. See LoadOverwrite.

terrain: SimpleLoadOverwrite?--

Overrides for the terrain section.

light: LoadOverwrite?--

Overrides for the Lighting section.

workspace: LoadOverwrite?--

Overrides for the Workspace section.

music: LoadOverwrite?--

Overrides for the SoundService (music) section.

material: LoadOverwrite?--

Overrides for the MaterialService section.

instance: SimpleLoadOverwrite?--

Overrides for the saved-instances section.

}

Functions​

Snapshot​

</>
Smapshot.Snapshot(
config: SnapshotConfig--

Describes what to capture and where to store the result.

) → Folder--

A snapshot containing the serialized map data.

Types

​

interface SnapshotConfig {
name: string?--

Name applied to the returned snapshot Folder.

saveLocation: Instance?--

If provided, the snapshot is parented here with a unique name.

saveDefaults: boolean?--

When true, properties that match Roblox defaults are still serialized.

terrainConfig: TerrainConfig?--

Terrain to capture. Omit to skip terrain.

lightingConfig: LightingConfig?--

Lighting properties and children to capture. Omit to skip lighting.

workspaceConfig: WorkspaceConfig?--

Workspace properties and children to capture. Omit to skip workspace.

musicConfig: MusicConfig?--

SoundService properties and children to capture. Omit to skip music.

materialConfig: MaterialConfig?--

MaterialService properties and material variants to capture. Omit to skip materials.

instanceConfig: InstanceConfig?--

Arbitrary instances to capture. Omit to skip instance saving.

}

Creates a snapshot of any combination of terrain, lighting, workspace, music, materials, and arbitrary instances based on the supplied SnapshotConfig. Any config field that is omitted is skipped.

The returned Folder can later be passed to Smapshot.Load to restore the captured state. If config.saveLocation is set, the folder is parented there with a unique name. 

local snapshot = Smapshot.Snapshot({
    name = "Arena",
    saveLocation = game:GetService("ReplicatedStorage"),
    terrainConfig = { slice = workspace.ArenaBounds },
    lightingConfig = { blacklist = { "Sky" } },
    workspaceConfig = { saveCameraCFrame = true },
    instanceConfig = { instances = { game:GetService("ReplicatedStorage").Arena.Weapons } },
})

IsCompatible​

</>
Smapshot.IsCompatible(
snapshot: Instance--

The snapshot you are trying to validate.

) → boolean--

The result of the validation.

Checks if the input has been made by Smapshot.Snapshot.

Smapshot.IsCompatible(Smapshot.Snapshot({})) -- true
Smapshot.IsCompatible(Instance.new("Folder")) -- false

ReadVersion​

</>
Smapshot.ReadVersion(
snapshot: Instance--

The snapshot to read the version from.

) → string?--

The stored version string, or nil if there is none.

Reads the Smapshot version string that was stamped onto a snapshot at creation time. Returns nil if the value is missing (e.g. the instance was not produced by Smapshot.Snapshot). 

Smapshot.ReadVersion(Smapshot.Snapshot({})) -- "0.2.0"
Smapshot.ReadVersion(Instance.new("Folder")) -- nil

GetAssetAsync​

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
</>
Smapshot.GetAssetAsync(
snapshotId: number--

Asset id of an uploaded snapshot.

) → Folder--

The loaded snapshot.

Gets a snapshot from a Roblox asset id.

The asset is fetched via AssetService:LoadAssetAsync and cached. Use Smapshot.Load to load the map snapshot. 

Smapshot.GetAssetAsync(1234567890)

Load​

</>
Smapshot.Load(
snapshot: Folder,--

The Snapshot to load.

config: LoadConfig?--

Optional LoadConfig describing how each section is applied: clear vs keep (keepDirty), clone vs consume (consume), or skip (ignoreOnLoad). Per-section values fall back to globalKeepDirty / globalConsume. Omit to clear and clone every section.

) → Folder--

The loaded snapshot.

Loads a snapshot folder previously produced by Smapshot.Snapshot.

Use Smapshot.LoadAssetAsync when loading from a Roblox asset id instead.

Smapshot.Load(snapshot)

-- Reset the workspace but consume everything else (cheaper, one-shot):
Smapshot.Load(snapshot, {
    globalConsume = true,
    workspace = { consume = false },
})

LoadAssetAsync​

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
</>
Smapshot.LoadAssetAsync(
snapshotId: number,--

Asset id of an uploaded snapshot.

config: LoadConfig?--

Optional LoadConfig describing how each section is applied: clear vs keep (keepDirty), clone vs consume (consume), or skip (ignoreOnLoad). Per-section values fall back to globalKeepDirty / globalConsume. Omit to clear and clone every section.

) → Folder--

The loaded snapshot.

Loads a snapshot from a Roblox asset id.

The asset is fetched via AssetService:LoadAssetAsync and cached for subsequent loads. Use Smapshot.Load when loading from an in-memory snapshot Folder instead. 

Smapshot.LoadAssetAsync(1234567890)
Show raw api
{
    "functions": [
        {
            "name": "Snapshot",
            "desc": "Creates a snapshot of any combination of terrain, lighting, workspace, music, materials,\nand arbitrary instances based on the supplied [SnapshotConfig]. Any config field that is\nomitted is skipped.\n\nThe returned `Folder` can later be passed to [Smapshot.Load] to restore the captured state.\nIf `config.saveLocation` is set, the folder is parented there with a unique name.\n\n```lua\nlocal snapshot = Smapshot.Snapshot({\n    name = \"Arena\",\n    saveLocation = game:GetService(\"ReplicatedStorage\"),\n    terrainConfig = { slice = workspace.ArenaBounds },\n    lightingConfig = { blacklist = { \"Sky\" } },\n    workspaceConfig = { saveCameraCFrame = true },\n    instanceConfig = { instances = { game:GetService(\"ReplicatedStorage\").Arena.Weapons } },\n})\n```",
            "params": [
                {
                    "name": "config",
                    "desc": "Describes what to capture and where to store the result.",
                    "lua_type": "SnapshotConfig"
                }
            ],
            "returns": [
                {
                    "desc": "A snapshot containing the serialized map data.",
                    "lua_type": "Folder"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 214,
                "path": "src/init.luau"
            }
        },
        {
            "name": "IsCompatible",
            "desc": "Checks if the input has been made by [Smapshot.Snapshot].\n\n```lua\nSmapshot.IsCompatible(Smapshot.Snapshot({})) -- true\nSmapshot.IsCompatible(Instance.new(\"Folder\")) -- false\n```",
            "params": [
                {
                    "name": "snapshot",
                    "desc": "The snapshot you are trying to validate.",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "The result of the validation.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 379,
                "path": "src/init.luau"
            }
        },
        {
            "name": "ReadVersion",
            "desc": "Reads the Smapshot version string that was stamped onto a snapshot at creation time.\nReturns `nil` if the value is missing (e.g. the instance was not produced by [Smapshot.Snapshot]).\n\n```lua\nSmapshot.ReadVersion(Smapshot.Snapshot({})) -- \"0.2.0\"\nSmapshot.ReadVersion(Instance.new(\"Folder\")) -- nil\n```",
            "params": [
                {
                    "name": "snapshot",
                    "desc": "The snapshot to read the version from.",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "The stored version string, or `nil` if there is none.",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 396,
                "path": "src/init.luau"
            }
        },
        {
            "name": "GetAssetAsync",
            "desc": "Gets a snapshot from a Roblox asset id.\n\nThe asset is fetched via `AssetService:LoadAssetAsync` and cached.\nUse [Smapshot.Load] to load the map snapshot.\n\n```lua\nSmapshot.GetAssetAsync(1234567890)\n```",
            "params": [
                {
                    "name": "snapshotId",
                    "desc": "Asset id of an uploaded snapshot.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "The loaded snapshot.",
                    "lua_type": "Folder"
                }
            ],
            "function_type": "static",
            "yields": true,
            "source": {
                "line": 414,
                "path": "src/init.luau"
            }
        },
        {
            "name": "Load",
            "desc": "Loads a snapshot folder previously produced by [Smapshot.Snapshot].\n\nUse [Smapshot.LoadAssetAsync] when loading from a Roblox asset id instead.\n\n```lua\nSmapshot.Load(snapshot)\n\n-- Reset the workspace but consume everything else (cheaper, one-shot):\nSmapshot.Load(snapshot, {\n    globalConsume = true,\n    workspace = { consume = false },\n})\n```",
            "params": [
                {
                    "name": "snapshot",
                    "desc": "The Snapshot to load.",
                    "lua_type": "Folder"
                },
                {
                    "name": "config",
                    "desc": "Optional [LoadConfig] describing how each section is applied: clear vs keep (`keepDirty`), clone vs consume (`consume`), or skip (`ignoreOnLoad`). Per-section values fall back to `globalKeepDirty` / `globalConsume`. Omit to clear and clone every section.",
                    "lua_type": "LoadConfig?"
                }
            ],
            "returns": [
                {
                    "desc": "The loaded snapshot.",
                    "lua_type": "Folder"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 437,
                "path": "src/init.luau"
            }
        },
        {
            "name": "LoadAssetAsync",
            "desc": "Loads a snapshot from a Roblox asset id.\n\nThe asset is fetched via `AssetService:LoadAssetAsync` and cached for subsequent loads.\nUse [Smapshot.Load] when loading from an in-memory snapshot `Folder` instead.\n\n```lua\nSmapshot.LoadAssetAsync(1234567890)\n```",
            "params": [
                {
                    "name": "snapshotId",
                    "desc": "Asset id of an uploaded snapshot.",
                    "lua_type": "number"
                },
                {
                    "name": "config",
                    "desc": "Optional [LoadConfig] describing how each section is applied: clear vs keep (`keepDirty`), clone vs consume (`consume`), or skip (`ignoreOnLoad`). Per-section values fall back to `globalKeepDirty` / `globalConsume`. Omit to clear and clone every section.",
                    "lua_type": "LoadConfig?"
                }
            ],
            "returns": [
                {
                    "desc": "The loaded snapshot.",
                    "lua_type": "Folder"
                }
            ],
            "function_type": "static",
            "yields": true,
            "source": {
                "line": 456,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "TerrainConfig",
            "desc": "",
            "fields": [
                {
                    "name": "slice",
                    "lua_type": "(BasePart | Region3int16)?",
                    "desc": "Region of terrain to save. If a `BasePart` is provided it is converted to a `Region3int16`. When `nil`, all terrain is saved."
                }
            ],
            "source": {
                "line": 32,
                "path": "src/init.luau"
            }
        },
        {
            "name": "LightingConfig",
            "desc": "",
            "fields": [
                {
                    "name": "whitelist",
                    "lua_type": "{ string }?",
                    "desc": "Names of `Lighting` children (effects, atmospheres, skies) to include. Mutually exclusive with `blacklist`."
                },
                {
                    "name": "blacklist",
                    "lua_type": "{ string }?",
                    "desc": "Names of `Lighting` children to exclude."
                }
            ],
            "source": {
                "line": 42,
                "path": "src/init.luau"
            }
        },
        {
            "name": "InstanceConfig",
            "desc": "",
            "fields": [
                {
                    "name": "instances",
                    "lua_type": "{ Instance }",
                    "desc": "Instances to capture."
                },
                {
                    "name": "saveParents",
                    "lua_type": "boolean?",
                    "desc": "When `true`, each instance's original parent path is recorded so it can be restored on load. Defaults to `false`."
                }
            ],
            "source": {
                "line": 53,
                "path": "src/init.luau"
            }
        },
        {
            "name": "WorkspaceConfig",
            "desc": "",
            "fields": [
                {
                    "name": "whitelist",
                    "lua_type": "{ string }?",
                    "desc": "Names of `Workspace` children to include. `Terrain` and `CurrentCamera` are always skipped here. Mutually exclusive with `blacklist`."
                },
                {
                    "name": "blacklist",
                    "lua_type": "{ string }?",
                    "desc": "Names of `Workspace` children to exclude."
                },
                {
                    "name": "saveCameraCFrame",
                    "lua_type": "boolean?",
                    "desc": "When `true`, the current `Camera.CFrame` is captured and restored on load."
                }
            ],
            "source": {
                "line": 65,
                "path": "src/init.luau"
            }
        },
        {
            "name": "MusicConfig",
            "desc": "",
            "fields": [
                {
                    "name": "whitelist",
                    "lua_type": "{ string }?",
                    "desc": "Names of `SoundService` children to include. Mutually exclusive with `blacklist`."
                },
                {
                    "name": "blacklist",
                    "lua_type": "{ string }?",
                    "desc": "Names of `SoundService` children to exclude."
                }
            ],
            "source": {
                "line": 77,
                "path": "src/init.luau"
            }
        },
        {
            "name": "MaterialConfig",
            "desc": "",
            "fields": [
                {
                    "name": "whitelist",
                    "lua_type": "{ string }?",
                    "desc": "Names of `MaterialService` children to include. Mutually exclusive with `blacklist`."
                },
                {
                    "name": "blacklist",
                    "lua_type": "{ string }?",
                    "desc": "Names of `MaterialService` children to exclude."
                },
                {
                    "name": "materialFilter",
                    "lua_type": "{ Enum.Material }?",
                    "desc": "If provided, only `MaterialVariant`s whose `BaseMaterial` is in this list are captured."
                }
            ],
            "source": {
                "line": 89,
                "path": "src/init.luau"
            }
        },
        {
            "name": "SnapshotConfig",
            "desc": "",
            "fields": [
                {
                    "name": "name",
                    "lua_type": "string?",
                    "desc": "Name applied to the returned snapshot `Folder`."
                },
                {
                    "name": "saveLocation",
                    "lua_type": "Instance?",
                    "desc": "If provided, the snapshot is parented here with a unique name."
                },
                {
                    "name": "saveDefaults",
                    "lua_type": "boolean?",
                    "desc": "When `true`, properties that match Roblox defaults are still serialized."
                },
                {
                    "name": "terrainConfig",
                    "lua_type": "TerrainConfig?",
                    "desc": "Terrain to capture. Omit to skip terrain."
                },
                {
                    "name": "lightingConfig",
                    "lua_type": "LightingConfig?",
                    "desc": "`Lighting` properties and children to capture. Omit to skip lighting."
                },
                {
                    "name": "workspaceConfig",
                    "lua_type": "WorkspaceConfig?",
                    "desc": "`Workspace` properties and children to capture. Omit to skip workspace."
                },
                {
                    "name": "musicConfig",
                    "lua_type": "MusicConfig?",
                    "desc": "`SoundService` properties and children to capture. Omit to skip music."
                },
                {
                    "name": "materialConfig",
                    "lua_type": "MaterialConfig?",
                    "desc": "`MaterialService` properties and material variants to capture. Omit to skip materials."
                },
                {
                    "name": "instanceConfig",
                    "lua_type": "InstanceConfig?",
                    "desc": "Arbitrary instances to capture. Omit to skip instance saving."
                }
            ],
            "source": {
                "line": 108,
                "path": "src/init.luau"
            }
        },
        {
            "name": "SimpleLoadOverwrite",
            "desc": "",
            "fields": [
                {
                    "name": "keepDirty",
                    "lua_type": "boolean?",
                    "desc": "When `true`, existing state is preserved instead of being cleared before this section is applied. Overrides `globalKeepDirty` for this section."
                },
                {
                    "name": "consume",
                    "lua_type": "boolean?",
                    "desc": "When `true`, the section's children are reparented into the target service instead of cloned, and the section is tagged so it is skipped on subsequent loads. Overrides `globalConsume` for this section."
                },
                {
                    "name": "ignoreOnLoad",
                    "lua_type": "boolean?",
                    "desc": "When `true`, this section is skipped entirely on load."
                }
            ],
            "source": {
                "line": 128,
                "path": "src/init.luau"
            }
        },
        {
            "name": "LoadOverwrite",
            "desc": "",
            "fields": [
                {
                    "name": "keepDirty",
                    "lua_type": "boolean?",
                    "desc": "When `true`, existing state is preserved instead of being cleared before this section is applied. Overrides `globalKeepDirty` for this section."
                },
                {
                    "name": "consume",
                    "lua_type": "boolean?",
                    "desc": "When `true`, the section's children are reparented into the target service instead of cloned, and the section is tagged so it is skipped on subsequent loads. Overrides `globalConsume` for this section."
                },
                {
                    "name": "ignoreOnLoad",
                    "lua_type": "boolean?",
                    "desc": "When `true`, this section is skipped entirely on load."
                },
                {
                    "name": "ignoreOnClear",
                    "lua_type": "{ Instance }?",
                    "desc": "Instances to leave in place when the target service is cleared (only applies when `keepDirty` is not set, since that is the only path that clears)."
                }
            ],
            "source": {
                "line": 142,
                "path": "src/init.luau"
            }
        },
        {
            "name": "LoadConfig",
            "desc": "",
            "fields": [
                {
                    "name": "globalConsume",
                    "lua_type": "boolean?",
                    "desc": "Default `consume` applied to every section that does not set its own. See [SimpleLoadOverwrite]."
                },
                {
                    "name": "globalKeepDirty",
                    "lua_type": "boolean?",
                    "desc": "Default `keepDirty` applied to every section that does not set its own."
                },
                {
                    "name": "globalIgnoreOnClear",
                    "lua_type": "{ Instance }?",
                    "desc": "Default `ignoreOnClear` applied to every clearing section (`Lighting`/`Workspace`/`SoundService`/`MaterialService`) that does not set its own. See [LoadOverwrite]."
                },
                {
                    "name": "terrain",
                    "lua_type": "SimpleLoadOverwrite?",
                    "desc": "Overrides for the terrain section."
                },
                {
                    "name": "light",
                    "lua_type": "LoadOverwrite?",
                    "desc": "Overrides for the `Lighting` section."
                },
                {
                    "name": "workspace",
                    "lua_type": "LoadOverwrite?",
                    "desc": "Overrides for the `Workspace` section."
                },
                {
                    "name": "music",
                    "lua_type": "LoadOverwrite?",
                    "desc": "Overrides for the `SoundService` (music) section."
                },
                {
                    "name": "material",
                    "lua_type": "LoadOverwrite?",
                    "desc": "Overrides for the `MaterialService` section."
                },
                {
                    "name": "instance",
                    "lua_type": "SimpleLoadOverwrite?",
                    "desc": "Overrides for the saved-instances section."
                }
            ],
            "source": {
                "line": 159,
                "path": "src/init.luau"
            }
        }
    ],
    "name": "Smapshot",
    "desc": "Smapshot allows for dynamic saving and loading of maps.",
    "source": {
        "line": 23,
        "path": "src/init.luau"
    }
}