> ## 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 Blockly: Block-Based Programming for Grades 4-8
> SAM Blockly is SAM Studio's block-based coding environment for grades 4-8. Snap together code blocks with text labels to build more complex programs.
SAM Blockly is the next step up from visual flow coding. Like Scratch, you snap colourful blocks together to build programs — but here each block carries a text label, so students start reading and writing real programming vocabulary. SAM Blockly replaces the older Google Blockly Workbench and runs entirely inside SAM Studio, making it easier to manage across a classroom.
## How SAM Blockly Differs from SAM Space
If you're deciding between environments, use this comparison to choose the right fit for your students:
| Feature | SAM Space | SAM Blockly |
| -------------------- | ----------------------- | ------------------------------------ |
| Audience | K–5 | Grades 4–8 |
| Block style | Icon-only, flow-based | Text-labelled, snap-together |
| Programming concepts | Visual cause-and-effect | Loops, conditions, variables, events |
| Text required | No | Yes (labels on blocks) |
| Virtual hardware | ✓ | ✓ |
| Cloud auto-save | ✓ | ✓ |
SAM Blockly introduces the building blocks of real programming — **loops**, **if/else conditions**, **variables**, and **events** — while keeping the drag-and-drop experience that removes syntax errors from the equation.
## Creating a SAM Blockly Project
Sign in and go to your dashboard.
Click **New Project**, enter a name, and click **Create**.
Choose **SAM Blockly** from the environment picker. The block workspace loads with a palette of categorised blocks on the left.
Blocks are grouped by type — **Inputs**, **Outputs**, **Logic**, **Loops**, **Math**, and **Variables**. Click a category to expand it and see what's available.
Drag blocks from the palette into the workspace and snap them together. Blocks only connect where they make logical sense, so mismatched types won't attach.
Pair your SAM Labs hardware over Bluetooth using the **Connect** button, or enable **Virtual** mode on any block to simulate it without physical devices.
Hit **Play** to run your program. Watch the hardware (or virtual blocks) respond, then adjust your code and run it again.
## What a Blockly Program Looks Like
Because SAM Blockly is visual, here's a written description of a simple example — a light-sensing lamp:
> **When the program starts**, set a variable called `brightness` to the value read from the **Light Sensor** block.
>
> Inside a **repeat forever** loop, check: **if** `brightness` **is less than 50**, then **turn on the LED** (set colour to white). **Else**, **turn off the LED** (set colour to black).
>
> At the end of the loop, **wait 500 milliseconds** before reading the sensor again.
In the Blockly workspace this looks like a stack of colour-coded puzzle pieces:
* A yellow **repeat forever** block wraps everything.
* Inside it, a green **if / else** block contains the condition.
* A blue **LED set colour** block sits inside each branch.
* An orange **wait** block closes the loop.
This structure teaches students that programs run **top to bottom**, that **loops** repeat actions, and that **conditions** choose between outcomes — all without writing a single character of text.
## Key Concepts SAM Blockly Introduces
Repeat a sequence of actions — forever, a set number of times, or while a condition is true.
Make decisions with **if**, **if/else**, and **if/else if** blocks that respond to sensor values or variable states.
Store and update values — like a sensor reading or a counter — and use them anywhere in your program.
Trigger code when something happens, such as a button press or a threshold being crossed.
## Virtual Hardware Support
You can run a complete SAM Blockly project without any physical hardware. Toggle the **Virtual** switch on each block in the hardware panel to simulate inputs (move a slider with your mouse) and watch virtual outputs respond in real time. This is ideal for homework assignments or days when the hardware kit isn't available.
SAM Blockly saves your project to the cloud automatically every 30 seconds. Look for the **Saved** indicator in the top bar — you never need to press a save button manually.
## Ready for More?
Once students are comfortable with loops, conditions, and variables in Blockly, they're ready to write real code. [SAM Script](/environments/sam-script) lets them see the JavaScript or Python that corresponds to their blocks — a natural bridge from visual to text-based programming.