> ## 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.

# SAM Script: JavaScript and Python for Advanced Coders

> SAM Script is SAM Studio's text-based coding environment. Write real JavaScript or Python to control SAM Labs hardware blocks for hands-on STEAM projects.

SAM Script is SAM Studio's most powerful coding environment. Instead of dragging blocks, you write real **JavaScript** or **Python** code directly in an editor — then watch that code bring physical SAM Labs hardware to life over Bluetooth. SAM Script is designed for upper-grade students, after-school clubs, and anyone who is ready to move beyond block-based programming into professional-grade languages.

<Info>
  SAM Script is currently in **beta**. Some features may change as we continue to improve the experience. We'd love your feedback — use the feedback button inside SAM Studio to share your thoughts.
</Info>

## Blocks View and Code View

SAM Script gives you two ways to work in the same project:

<Tabs>
  <Tab title="Blocks View">
    The Blocks view shows a visual representation of your program using labelled blocks — similar to SAM Blockly. Use it to sketch out your logic quickly or to help newer coders follow along with what the program does.
  </Tab>

  <Tab title="Code View">
    The Code view shows the actual JavaScript or Python source code for your program. Every change you make here is reflected instantly in the Blocks view, and vice versa. This two-way sync makes SAM Script an excellent bridge from block-based to text-based thinking.
  </Tab>
</Tabs>

Switch between views at any time using the **Blocks / Code** toggle at the top of the editor. You can start in Blocks view, switch to Code view to see what was generated, and then edit the code directly — a great way to demystify programming for students who are making the transition.

## Creating a SAM Script Project

<Steps>
  <Step title="Open SAM Studio">
    Sign in and navigate to your dashboard.
  </Step>

  <Step title="Start a new project">
    Click **New Project**, give it a name, and click **Create**.
  </Step>

  <Step title="Select SAM Script">
    Choose **SAM Script** from the environment picker. The code editor opens with a starter file.
  </Step>

  <Step title="Choose your language">
    In the top bar, select either **JavaScript** or **Python** from the language dropdown. You can switch languages at any time — your code will be converted automatically where possible.
  </Step>

  <Step title="Pair your hardware">
    Click **Connect** and follow the Bluetooth pairing prompts to link your SAM Labs blocks. Physical hardware is recommended for SAM Script, as it gives students immediate, tangible feedback.
  </Step>

  <Step title="Write your program">
    Type your code in the editor. Use the SAM API to read sensor values and control output blocks (see the examples below).
  </Step>

  <Step title="Save and run">
    Press **Ctrl + S** (or **Cmd + S** on Mac) to save your file, then click **Run** to execute it. Watch your hardware respond in real time.
  </Step>
</Steps>

## Code Examples

Here are two equivalent programs that blink an LED on and off every second — one in JavaScript and one in Python.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // Blink an LED every second
    const led = await SAM.connect('led');
    while (true) {
      await led.setColor(255, 0, 0);
      await SAM.wait(1000);
      await led.setColor(0, 0, 0);
      await SAM.wait(1000);
    }
    ```

    * `SAM.connect('led')` finds and pairs the LED block over Bluetooth.
    * `led.setColor(r, g, b)` sets the colour using red, green, and blue values from 0–255.
    * `SAM.wait(1000)` pauses execution for 1000 milliseconds (one second).
    * The `while (true)` loop repeats the blink indefinitely until you press **Stop**.
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import sam

    led = sam.connect('led')
    while True:
        led.set_color(255, 0, 0)
        sam.wait(1000)
        led.set_color(0, 0, 0)
        sam.wait(1000)
    ```

    * `sam.connect('led')` pairs the LED block over Bluetooth.
    * `led.set_color(r, g, b)` sets the LED colour using 0–255 values for red, green, and blue.
    * `sam.wait(1000)` pauses for 1000 milliseconds.
    * `while True:` loops forever — press **Stop** in SAM Studio to end the program.
  </Tab>
</Tabs>

## Key Features

<CardGroup cols={2}>
  <Card title="Real languages" icon="code">
    Students write genuine JavaScript or Python — the same languages used by professional developers. Skills transfer directly beyond the classroom.
  </Card>

  <Card title="Two-way Blocks ↔ Code sync" icon="arrows-left-right">
    Switch between Blocks view and Code view at any time. Changes in one view are reflected in the other, making the transition from visual to text-based coding seamless.
  </Card>

  <Card title="Physical hardware first" icon="microchip">
    SAM Script is optimised for use with real SAM Labs blocks connected over Bluetooth, giving students tactile, real-world feedback for their code.
  </Card>

  <Card title="Full SAM API access" icon="book-open">
    Unlock the complete SAM Labs hardware API — read raw sensor data, chain multiple blocks, set precise timing, and build logic that goes far beyond what block-based environments support.
  </Card>
</CardGroup>

## Saving Your Work

<Warning>
  **SAM Script saves projects locally to your device — not to the cloud.** Your code is not automatically synced. Remember to press **Ctrl + S** (Windows) or **Cmd + S** (Mac) regularly while you work. If you close the browser tab or the app without saving, unsaved changes will be lost.
</Warning>

Get into the habit of saving before you run, before you switch views, and before you leave your seat. It's a great real-world practice that mirrors professional software development workflows.

<Tip>
  For full SAM Script documentation — including the complete API reference, a list of all supported hardware blocks, and advanced examples — head to the [SAM Script section](/sam-script/editor).
</Tip>

## Who Should Use SAM Script?

SAM Script is best suited for:

* **Grades 7 and up** who have already completed projects in SAM Blockly.
* **After-school coding clubs** working on advanced STEAM challenges.
* **Teachers** who want to introduce a real programming language alongside physical computing.
* **Students preparing for AP Computer Science** or other programming courses who want hands-on hardware experience.

If your students are still getting comfortable with loops and conditions, start them in [SAM Blockly](/environments/sam-blockly) and progress to SAM Script when they're ready to type their first line of code.