Skip to main content
Virtual blocks are on-screen software emulations of physical SAM Labs hardware. They look and behave like the real blocks — you can press a virtual button, watch an LED change color, or see a motor start spinning — all without any physical hardware in the room. This makes them a powerful tool for testing your code, exploring ideas early, or running lessons remotely.

​
Why Use Virtual Blocks?

No Hardware Required

Write and run SAM Script programs from any device, even when physical blocks are unavailable or not yet distributed.

Faster Testing

Instantly reset, reconnect, and re-run without charging or re-pairing a physical block.

Distance Learning

Students working from home can interact with virtual blocks over their browser — no Bluetooth or physical kit needed.
Virtual blocks are perfect for demonstrating code to the whole class on a projector. Run your script live and let students see the virtual LED change color or the virtual button register a press — no need to hold up a small physical block for everyone to see.

​
How to Enable Virtual Blocks

1

Open the Virtual Blocks panel

In the SAM Script editor, click the Virtual Blocks toggle or button in the toolbar. The panel activates immediately — no page reload required.
2

See the virtual block representations

On-screen representations of each block type appear in the Virtual Blocks panel. They update in real time as your code runs.
3

Interact with the virtual blocks

You can click or interact with virtual blocks directly:
  • Button — click it to simulate a press and release.
  • LED — watch the color and brightness change as your code sets them.
  • Light sensor — drag the slider to simulate different ambient light readings.
  • Motor and Servo — see animated indicators showing speed, direction, and angle.

​
Same API, Real or Virtual

You do not need to change a single line of code when switching between virtual and physical blocks. The connect call works identically in both cases: 
// This works with a physical block AND with a virtual block
const led = await SAM.connect('led');
await led.setColor(255, 100, 0);

# Same in Python — no changes needed for virtual vs physical
led = sam.connect('led')
led.set_color(255, 100, 0)
SAM Script detects whether a paired physical block is available. If one is connected, it uses the physical block. If not, it falls back to the virtual block automatically.

​
Limitations of Virtual Blocks

Virtual blocks simulate behavior but cannot replicate everything a physical block does. Keep the following in mind when testing with virtual blocks.
Virtual blocks have no Bluetooth radio. They cannot be detected by other devices and do not appear in the Pair dialog. They exist only within the SAM Script session that created them.
Sensors like the light sensor return simulated values based on slider controls in the Virtual Blocks panel. These values are controlled by you or your students rather than reflecting a real physical environment.
A virtual buzzer will not produce sound through a speaker, and a virtual motor will not turn a physical wheel. Always validate final projects with real hardware before presenting them.

​
Switching from Virtual to Physical

When you are ready to run your code on real hardware, simply pair a physical block following the Pairing guide. Once the physical block connects, SAM Script uses it in place of the virtual block — no code changes required. The virtual block remains on screen as a visual reference but the physical block takes over all input and output.