Simcraft Docs

Embed a model in your site#

This guide shows you how to embed a Simcraft model in your page. Readers can run the model and open it in Simcraft, but they can't change it.

An embed is an <iframe>. Your page needs no Simcraft code and no build step. You share the model first, because only a shared model can be embedded.

Intended use#

Use an embed on a page about a model: a lesson, a course page, a post, or an explanation of how a system behaves. Your readers run the model where they would otherwise see a picture of it.

If you're building an application on simulation, an <iframe> is the wrong tool. Use the WebAssembly engine, the TypeScript client, or the Python SDK, which run a document and give you its event stream. See the reference implementation.

Share the model, then copy the snippet#

  1. Open the model in Simcraft and press Share.
  2. Turn on Share with anyone who has the link.
  3. Copy the snippet beside Embed.

The snippet looks like this:

html
<iframe
  src="https://app.simcraft.io/embed/models/7a1f4d2e-9c3b-4f55-8e21-6d4a0b9c7e13"
  title="Clinic"
  width="100%"
  height="520"
  style="border:0"
></iframe>

Paste it into your page. The frame fills the width of its column. An <iframe> doesn't grow to fit its content, so you set the height.

Screen readers announce the frame by its title, which the snippet sets to the model's name. Change it if your page calls the model something else.

If you turn sharing off, the embed stops loading and says the model is not shared.

Settings#

Add settings to the embed address as query parameters. Each one changes what readers see.

ParameterValuesDefaultEffect
header1, 01The bar with the model's title, a View only label, and Open in Simcraft
controls1, 01The run bar, which plays, steps, and resets the run, and opens its results
inspect1, 01The Inspect panel, which opens when the reader selects a component
code1, 00A Code button in the header, which shows the model's OSDL
themelight, dark, autoautoThe theme. auto follows the reader's system setting and changes with it
experimentan experiment's namethe model's firstThe experiment the page opens with
autorun1, 00Whether the run starts as the page loads

This snippet runs the model as the page loads, with no header and no Inspect panel:

html
<iframe
  src="https://app.simcraft.io/embed/models/7a1f4d2e-9c3b-4f55-8e21-6d4a0b9c7e13?header=0&amp;inspect=0&amp;autorun=1"
  title="Clinic"
  width="100%"
  height="320"
  style="border:0"
></iframe>

With header=0 there is no Code button, so code=1 opens the embed in the code view. The code view hides the run bar, so readers of that embed can't run the model.

If the model has no experiment with the experiment name, the embed opens the model's first experiment.

A value that isn't in this table leaves the setting at its default, so a typo in the address still shows the model.

Size#

Make the frame at least 320 by 420 pixels. Below that, the diagram is too small to read.

These measurements use the quickstart's M/M/1 queue. The diagram's height is the space between the header and the run bar.

FrameHeaderDiagram
400 × 520two rows, 70px310px
320 × 420two rows, 70px160px
400 × 320two rows, 70px110px
860 × 560one row, 45px395px

At 420 pixels wide or less, the header puts its buttons on a second line under the title. The run bar fits at every size in the table. It is 80 pixels tall in the 860-pixel frame, and 100 pixels tall, in two rows, in the narrower frames.

A shorter frame works if readers don't need to run the model. Set controls=0 to show the diagram alone, and add autorun=1 to animate it.

Readers open a run's results with Results in the run bar. The embed never opens them by itself, because they would cover the model. In a frame narrower than 760 pixels the results fill the frame, and their close button returns to the model.

Limits#

The model must be shared#

You can embed only a shared model. For a private or deleted model, the embed says the model is not shared.

Readers cannot edit#

Every embed is view-only, and no setting changes that. To change the model, a reader presses Make a copy in the Inspect panel, which opens their own copy in a new tab. Open in Simcraft opens the model view-only in the app, where they can also make a copy. Your model never changes.

The run happens in the reader's browser#

An embed runs the model in the reader's browser, on the WebAssembly engine. A run needs no account and sends nothing to a server. If the browser can't load the engine, the embed says so. It never falls back to a server.

The read limit for each network#

Each embed that loads counts as one read of a shared model, and so does each visit to a model's link. Simcraft allows 60 reads a minute from one IP address. Over the limit, a reader sees "Too many requests. Try again in a minute.", and the embed loads if they reload a minute later. A class on one school network can reach the limit by opening a page with several embeds.

Simcraft is pre-alpha. The embed address, its settings, and the frame's appearance can all change.