Overview

A ShotScript project is one .ssp file that holds its whole tree, and its kind is System, Generic or Roblox.

One file

• <Name>.ssp holds folders, .shot files (ShotScript), .luau files (plain Luau) and Value instances.
• shot run takes the file; other commands take --project Station.ssp.
• shot shows the tree inside as a folder of files: shot show Station/Station.shot (One-file projects).
• The header comes first: shotsystem 1, the kind, and the export: the program shot run runs, or what other projects use.

The three kinds

shot new makes each:

shot new Demo.ssp
shot new Units.ssp --kind Generic
shot new Rbx.ssp --kind Roblox

They print:

made Demo.ssp: a System project, whose program Main.shot prints a line (shot run Demo.ssp, or shot open Demo.ssp)
made Units.ssp: a Generic project, the library Units (Units/Units.shot) that any project can use: plain Luau and the shared datatypes, no services (shot open Units.ssp)
made Rbx.ssp: a Roblox project, the library Rbx (Rbx/Rbx.shot); shot check checks it, and building it for Roblox comes later (shot open Rbx.ssp)

shot run Demo.ssp prints Hello from Demo.

• System is the default (--kind System), also for a header without a kind line. It has the services and makes its own instances (Services, Instances).
• Generic has no services, so any kind may use it. A service in one is an error:

Gen.ssp/Gen/Gen.shot:3:5   FileService is a System project's service: a Generic project has none (plain Luau and the shared datatypes, so it runs in any project)

• Roblox in an .ssp file is a library shot check checks, without services and without Roblox's own API yet (game:GetService is refused). Roblox games are folder projects.

Using another kind is an error at its line (Externals, THE KINDS RULE).

The examples

The System pages share three projects in one folder:

Externals shows Units and Station. Forecast's program:

Main/Main.shot

use TimeService
use RunService
use external "Station.ssp"

local station = Station.LoadAsync(root.File.Value)
for _, word in RunService.Arguments do
    local fahrenheit = tonumber(word)
    if fahrenheit then
        station:AddFahrenheit(fahrenheit)
    end
end
local saved, why = station:SaveAsync()
if not saved then
    error("couldn't save: " .. tostring(why))
end
print(`{#station.Readings} readings, average {station:Average()} C`)
print("summary made " .. TimeService:Iso(TimeService:Now()))

Run it:

shot run Forecast.ssp -- 50 61 72

It prints (the second line is the run's time):

3 readings, average 16.1 C
summary made 2026-10-20T06:18:28Z

• use external "Station.ssp" gives the file Station's class. The run runs Station's code and the Units code it uses (Externals).
• Services are instances: call them with a colon, TimeService:Now() (Services).
• root.File is the StringValue at the root of Forecast's tree; its Value names the JSON file (One-file projects, ROOT AND SCRIPT).
• The words after -- are RunService.Arguments (One-file projects, RUNNING A PROGRAM).
• readings.json lands beside Forecast.ssp, in the project file's folder (FileService). The next run loads it first.

The order of work

shot map --project Station.ssp prints:

Shot project Station.ssp: 2 files in 1 folders
kind System: it can only use System and Generic projects
export Station: a library, Station/Station.shot
external Units: "Units.ssp", interface 62f942db347c

Station/      class Station  Temperature readings in Celsius, kept in a JSON file
  Types.shot  types

Next: shot outline <folder or name>, shot find <name>, shot show <Name.Member>, shot docs

After changing a project others use, check its users (Externals, WHEN A USED PROJECT CHANGES).

Read next

These pages, for System and Generic projects, in order:

The language pages hold on every kind. Their examples are Roblox games: read @shot.Wallet as root.Wallet (One-file projects, USING A MODULE).

For Roblox projects only: Adopt, Compiled, Invariants, Remotes, SaveLock, Scripts and SplitAndSides. Files is the Roblox layout; its BOOKMARKS section holds everywhere.