> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samstudio.net/llms.txt
> Use this file to discover all available pages before exploring further.

# The SAM Script Editor: Blocks, JavaScript, and Python

> SAM Script's editor lets you switch between a Blocks view and a code view (JavaScript or Python) to program SAM Labs hardware from within SAM Studio.

SAM Script is the built-in programming environment inside SAM Studio. It gives you three ways to write programs for your SAM Labs hardware: a visual Blocks editor, a JavaScript text editor, and a Python text editor. You can switch between these modes at any time, and SAM Studio will do its best to translate your work across them.

## Editor modes

SAM Script offers three editing modes. Each mode is suited to a different level of experience or workflow.

<CardGroup cols={3}>
  <Card title="Blocks" icon="puzzle-piece">
    Drag and drop visual blocks to build your program. A live code preview shows the equivalent JavaScript as you work — a great way to learn how code maps to visual logic.
  </Card>

  <Card title="JavaScript" icon="js">
    Write JavaScript directly in a text editor. Full access to the SAM object API, async/await patterns, loops, and conditions. Ideal for students comfortable with text-based coding.
  </Card>

  <Card title="Python" icon="python">
    Write Python in a clean text editor. Uses the `sam` module with snake\_case methods. A natural fit if you already know Python from school or other projects.
  </Card>
</CardGroup>

## Switching modes

The mode toggle sits at the top of the editor. Click **Blocks**, **JavaScript**, or **Python** to switch.

<Note>
  Switching from Blocks to JavaScript or Python converts your visual program into code automatically. Switching back from code to Blocks may not always be possible if your code contains patterns the Blocks editor cannot represent — SAM Studio will warn you before any work is lost.
</Note>

## The toolbar

The toolbar runs along the top of the editor and gives you quick access to the most important actions:

| Button   | What it does                                                     |
| -------- | ---------------------------------------------------------------- |
| **Run**  | Uploads and executes your program on the connected SAM hardware. |
| **Stop** | Halts the currently running program.                             |
| **Save** | Saves the project to your local storage.                         |

<Warning>
  SAM Script saves your work **locally on this device**. Always click **Save** before closing SAM Studio or switching projects — unsaved changes cannot be recovered.
</Warning>

## The block palette

In Blocks mode, the panel on the left side of the screen is the **block palette**. It organises available blocks into categories:

* **Hardware** — blocks for your connected SAM devices (LEDs, motors, buttons, sensors, and more)
* **Control Flow** — if/else branches, wait blocks, and program start triggers
* **Variables** — create and update named values in your program
* **Logic** — comparisons and boolean operators (AND, OR, NOT)
* **Loops** — repeat, while, and for-each structures

Drag any block from the palette onto the canvas to add it to your program. Blocks snap together automatically when they are compatible.

## The canvas and code area

The large panel on the right is where you build or write your program:

* In **Blocks mode**, this is the **canvas** — a free-form workspace where you connect blocks together.
* In **JavaScript or Python mode**, this is a **text editor** with syntax highlighting, line numbers, and basic autocomplete for SAM APIs.

In Blocks mode, a collapsible **code preview** panel shows the JavaScript equivalent of your current block arrangement. Use it to build intuition for how visual logic translates into real code.

## Console output

The **Console** panel sits at the bottom of the editor. It displays:

* Output from `console.log()` (JavaScript) or `print()` (Python) calls in your program
* Runtime errors and connection messages
* Confirmation messages when your program starts and stops

Click the **Clear** button inside the console to remove old output before a new run.

***

## Creating your first SAM Script project

<Steps>
  <Step title="Open SAM Studio and start a new project">
    Launch SAM Studio. From the home screen, click **New Project**.
  </Step>

  <Step title="Select SAM Script">
    In the project type picker, choose **SAM Script**. This opens the script editor rather than the flow-based canvas.
  </Step>

  <Step title="Give the project a name">
    Type a name for your project in the dialog that appears, then click **Create**. Choose something descriptive — you can always rename it later.
  </Step>

  <Step title="Choose your mode">
    At the top of the editor, select the mode you want to start in: **Blocks**, **JavaScript**, or **Python**. Not sure which to pick? Start with Blocks and switch to code when you feel ready.
  </Step>

  <Step title="Connect your hardware">
    Make sure your SAM Labs blocks are powered on and in range. SAM Studio will detect them automatically. You'll see connected blocks listed in the Hardware section of the block palette (Blocks mode) or available via the `SAM.connect()` / `sam.connect()` API (code modes).
  </Step>

  <Step title="Click Run to execute your program">
    When you're ready, click the **Run** button in the toolbar. SAM Studio sends your program to the hardware and begins executing it. Watch the Console for output and any error messages.
  </Step>
</Steps>

<Tip>
  If a block doesn't respond when you click Run, check the Console for a connection error. Try turning the block off and on again, then clicking Run once more.
</Tip>