Dynamics & Recording
Every scenario keeps a design, a record of what its machines did, and the events planned over it. A label says whether a scenario describes what is on the site or what could be, recording mode logs your own edits instead of revising the design, and any scenario can be locked against casual changes.
Overview
Every scenario carries a label: hypothetical (it describes what could be — a plan, an alternative, a milestone) or as-built (it describes what is on the site). The label is a statement about the scenario and nothing more: it changes nothing about how the scenario is edited, what it records or which copy runs it. Mark a scenario as-built from its row in Sites & Scenarios; a copy always starts hypothetical, because nobody has said the copy is the record.
Two ways time enters a scenario
Recording is the running history of a scenario — sensor readings, trigger runs and the firings of rules that fetch outside data — kept as a timestamped log rather than overwriting the current state. Any scenario with such machine work records it, as-built or hypothetical.
Events are changes to values at a time or in a repeating pattern — a construction phasing plan, a seasonal irrigation calendar — held in the scenario, on its own timeline or in named groups that can be switched on and off. An edit you make away from now, or in recording mode, is an event too.
The next three sections cover what a recording holds and how to read it, how events and their groups are made and when they take effect, and how to replay that history. The two after them cover the two safeguards you’ll actually run into while editing: recording mode, and the baseline lock, which any scenario can carry.
Recordings
A scenario’s recording is its history: a list of entries, each one a change that happened on the site.
What an entry holds
Each entry holds when the change happened, which values changed (the old value and the new one), and where it came from — a person’s edit, a sensor reading, a trigger, a rule, or a simulation. The row history shows that origin as a short label on each entry.
Entries are added, not rewritten
A later change becomes a new entry; earlier entries stay as they were. That is what lets you move the time cursor back and see the site as it was at that moment.
To read one row’s events, right-click the row in the Data tab and choose Show events for this row. Clicking an entry moves the time cursor to it.
Fixing a wrong value
The row history can remove an event a person made, planned or recorded, but not an entry a machine recorded. To correct a value a machine recorded wrong, enter the right value in recording mode. It applies from that moment on, and the history keeps both entries, so times before the correction still show the old value.
Unlocking the baseline doesn’t change a recorded value. The baseline is the starting state underneath the history, and a recorded entry takes precedence over it from the entry’s time on — see Baseline Lock for when unlocking is the right call.
Everyone sees the same recording
Everyone who can open the scenario sees the same recording: an entry written on one device reaches the others like any other edit, and one written offline is sent on the next connection.
Events and Rules
An event gives one row new values from a moment on. Events belong to the scenario: a copy of the scenario carries its own copy of them, everyone who can edit the scenario can change them, and everyone who can open it sees their values. Where two events change the same cell, the later one in time wins.
Adding an event
The usual way is to edit. Move the clock to the time, or switch to recording mode at now, and change the cell, the property or the transform: the edit is stored as an event at the clock’s time and the design stays as it was (see Replay and Recording Mode). To plan a change to one cell without moving the clock, choose Schedule a change to this cell… from its right-click menu in the Data tab; Add event… in the Events drawer does the same for any cell.
Groups
An event sits on the scenario’s own timeline or in a named group, which gives it its timing. In an Absolute group times are real dates and times, so each event happens once; in a Repeating one times are counted from an anchor, and everything in the group happens again every period. Each group has a switch: switched off, its events and rules are held without being removed. Any number of groups apply at once, and their order changes nothing.
Building a repeating pattern
In the Events drawer, choose Show one cycle on a repeating group, then edit with the clock away from now or in recording mode. Each edit is stored in that group at its point in the cycle, so it happens again in every cycle, and the line beside the name in the Inspector says so, for example Records in Irrigation at 6 hours into each cycle. Show everything, or closing the drawer, sends edits back to the scenario’s own timeline.
The Events drawer
The calendar button in the status bar opens the Events drawer, which lists every event of the scenario, past and upcoming together. Upcoming holds each event with a next occurrence, soonest first from the time cursor, with the two after it underneath; Past holds the rest, newest first — a one-time change in the past still applies from its time. Each row names its group, or reads This scenario. Go to moves the time cursor to the occurrence shown, Change… edits an event’s value, time or group, and Remove takes it out of the scenario. Its groups are listed with their timing and switches, and New group… makes one. A rule that reads the weather or runs a script cannot be predicted, so its row gives the reason in place of a time. The list also holds the scenario’s timed triggers — triggers that run an operation at a set time — each with its own switch, when it last ran, and Change… to open it in its editor.
The kinds of rule
A group can also hold rules, instructions that produce values over time. A cron rule sets one cell to a given value on a calendar pattern, such as every Wednesday at 06:00. A calendar pattern reads real dates, so a cron rule goes in an Absolute group: a Repeating group counts time from the start of each cycle, which no calendar can read, so the editor refuses a cron rule in one and refuses to make a group that holds one repeat.
A computed rule is a short script that gives values for the cells it names as a function of time. It runs isolated, with no access to the site’s data or to the network, and a script that fails or runs for more than one second gives no value.
A derivative rule transforms the values of another rule in the same group: it offsets, scales or delays them, or turns them into one of two values at a threshold or with hysteresis.
These three kinds are worked out when a value is read, on any scenario and at any time the clock is set to. They are never written into a recording, and which copy of the scenario was running when a strike fell due changes nothing they say.
Weather readings from the US National Weather Service come into a group as rules too, and they are the exception: a reading fetched at one moment cannot be fetched again for a past one, so the copy running the scenario writes each reading into the recording as it arrives, and a moment nothing was running for stays unrecorded. No rule reads the site’s own data; to act when a condition on the site holds, use a trigger.
Adding, changing and stopping a rule
There is no form for a rule: ask the AI assistant to add or change one, or do it from a script through the toolkit. A new rule applies from the current time unless you say otherwise, so adding one to an as-built scenario never rewrites its past; a rule meant to hold for all time, as on a hypothetical scenario modeling a whole year, is created that way on purpose. Changing a rule applies from a chosen date (the current time by default): what the rule gave before that date is kept, and its row in the drawer reads since <date>. In the drawer a rule’s row has its own switch and Remove. Switching a rule off holds it without removing it; a weather rule switched back on does not record what fell due while it was off. Removing a rule keeps what a weather rule already recorded. Switching a group off stops every rule in it.
When an event takes effect
An event takes effect at its own time on every copy of the scenario, whether or not anything was running then: move the clock to that time and the value is there, in the past as well as ahead. A reading recorded after it, such as a sensor’s, wins from the time of the reading.
A weather rule is different. Whichever copy runs the scenario — this browser or a Sim, as the line at the top of the drawer says — checks once a minute and writes each reading that has fallen due into the recording, with the origin procedural. A scenario with a weather feed has such a copy whatever its label; one with no feed, trigger or recorded rule has none, and needs none. Each is recorded at the moment it was carried out, which is when it took effect on the site, and the time it was due is kept with it. A cron, computed or derivative rule is not carried out at all: it is worked out whenever a value is read.
Firings that fell due while nothing was running, such as overnight with the browser closed, are carried out the next time something runs, up to 7 days back; older ones are skipped. Switching a group back on does not carry out what fell due while it was off. Once recorded, a firing no longer depends on the rule that produced it: switching the group off or deleting it leaves the recorded value in place.
On a scenario with no feed, trigger or recorded rule nothing is recorded. What you see at a moment is what the events and rules give for that moment, worked out when you look.
Replay
Because earlier entries stay as they were, you can go back through a scenario’s history. Moving the time cursor into the past shows the site as it was at that moment, and playing it shows the recorded and planned changes happen in order — to see how a value developed, or to check what the site looked like on a given day.
Moving through time
The time controls in the status bar move the clock: step back or forward, or click the time display and type a date. Hold the time display and drag to scrub — left or right to run the time, up or down to move a day at a time, faster the farther you drag.
The timeline panel, opened with the timeline button in the status bar, is that same scrubber kept open across the bottom of the screen. Drag along it to scrub, or click a point on it to move the clock there; with it focused, the arrow keys step the clock. It also shows the events in view, past and upcoming, and clicking one moves the clock to it.
Moving the cursor always pauses playback, so after a drag or a jump you are paused at that moment.
Playing it back
The play button in the status bar plays forward at normal speed from wherever the clock is, and pauses it again. For another speed, or to play backwards, pick a rate from the status bar’s rate menu; negative rates play backwards. While the cursor is in the past, the status pill in the status bar reads REPLAY; ahead of now it reads FUTURE.
The 3D view and the Data tab follow the cursor, showing each value as it was at that time.
While you’re away from Live
At any time other than now, past or future, an edit records an event at that time instead of changing the design, on every scenario: move a valve, set a property or edit a Data-tab cell, and the scenario reads the new value from that moment on while the design stays as it was. The status bar and the scene say so: the Mode pill reads Recording, the 3D view gets an orange frame and, in its bottom-right corner, a Recording at <time> label with its own Return to now. Adding, deleting or re-parenting an entity or row is refused there, because the structure of a scenario is timeless for now; make that change in the design at now, or in a milestone scenario. Ctrl+Z after a recorded edit removes that event. Click the status pill to return to the present, or open the ▾ beside it for Return to now. A point selected in the history browser (below) is a separate, read-only position with its own Return to current and Branch from here; the clock stays where it is either way.
Change flags pause too. The scene shows a “Change flags paused while viewing history” label; its ⓘ explains why.
Not the same as “as of”
Replay moves through what happened on the site. The history browser (next section) instead selects one point in the database’s history for the whole session: the scene, the Data tab and the inspector then show the scenario as the database held it at that point, read-only, at whatever simulation time the clock is at.
History
Every change saved to a scenario is a transaction in its database, and the history browser lists them: open the Data tab and click History. Each point shows when it was saved, who or what made it — you, a collaborator, a sensor, a trigger, a rule — and what it changed; click a point to see every changed value, before and after. Stretches in which nothing was written are condensed on the axis above the list, and new transactions appear as they arrive.
Viewing the database as it was
Type a date and time at the top of the browser and press Go, or press View as of here on a point, to show the whole scenario as the database held it then: the scene, the Data tab, the inspector, the recording and the events alike. The status pill reads PAST and the scenario is read-only. Return to current — in the browser, under the Data tab’s toolbar, in the status pill’s ▾ and in the scene’s corner label — brings the current database back; Branch from here starts a branch at that point so you can make a change from there.
The simulation clock is a separate position and stays where it is when a point is selected or left, so you can read, for instance, what was planned for tomorrow in the database as of yesterday. Return to now moves only the clock; with both off, the ▾ offers both.
Keeping a record of a period
To keep a record of the scenario — to close a period, say — export an archive: Export archive of the current state… on the history browser’s newest point, or Export Scenario in the Sites & Scenarios panel and the Archive format. An archive is a read-only file you keep, holding every row of the scenario and its recordings and its state at the period end you choose, with a checksum and, if you choose keys to sign with, your signatures. Later versions of SiteCAD can still check it, whatever storage format they use. While the file is written, the scenario is shown read-only as it stood when the export began. Changes recorded by then that are dated after the period end are in the file too. To close a period after the fact, select a past point and press Export archive from this point… on its row: the archive holds the scenario as the database stood then, as far back as the history browser can show. Keep the point selected until the file is written; to lock the period too, return to now and lock it from the history browser.
Narrowing and how far back
The chips above the list narrow it to one table, to one origin, or — from a row’s right-click menu, Show history for this row — to the transactions that wrote to one row. Online, the list goes on into the server’s history, and the line at the bottom says where full detail begins; a point older than this device’s is downloaded from the server to be shown, and cannot be branched from. On a branch, its own changes are listed above the line it came from, and any of them can be shown and branched from: Branch from here on one makes a branch of that branch.
Recording Mode
Every edit you make answers one question: is this revising the design, or logging what actually happened? SiteCAD answers it with two edit modes, shown and switched by the Mode pill in the status bar.
Recording vs. Design edits
Design mode revises the design itself. Every scenario opens in design mode, whatever its label and whatever mode it was left in.
Recording mode logs your edit into the scenario’s history at the current moment — it’s how you tell SiteCAD “this really happened” without touching the design. You switch into it, and back out, by clicking the pill, on any scenario; neither direction asks for confirmation. In design mode, a value that a planned change or a rule already governs becomes an event at now too, since a design edit would not show through it; the Inspector says so beside the value.
The recording holds values, not structure. Changing a value — a property, a transform, an attribute’s value — is recorded; adding, renaming or deleting an attribute, like moving an entity to another parent, changes which things the scenario has, and is refused in recording mode. Switch to design mode to change which attributes an entity has.
This setting is about your own edits only
Sensor readings, trigger runs and the firings of rules that fetch outside data are always logged to the recording, on any scenario that has them, no matter how this setting is set. Recording mode only controls whether your own manual edits get logged too — turning it off doesn’t pause or hide anything else that’s happening on the site. A device’s track is a machine reading too: Record Track works on any scenario while the clock is at now, in either mode.
Baseline Lock
Any scenario can be locked, hypothetical or as-built. The lock is a reminder that a scenario is settled — an agreed plan, the record of what is built, the scenario a running site depends on — so that it doesn’t change by accident. Everyone who opens a locked scenario sees it locked, and edits to it are refused until you unlock it for yourself. Its name, description and notes stay editable.
Assigning a Sim instance to a scenario locks that scenario once, when the instance first syncs it, because a running site depends on it. A branch of a locked scenario starts without the lock; an imported or restored copy keeps it.
Locking a scenario and removing its lock
To lock the open scenario, click the padlock button, Lock scenario, on its row in Sites & Scenarios. On a locked scenario the same button is Remove lock, and it asks you to confirm, because afterwards everyone can edit the scenario without unlocking it first. Ctrl+Z undoes neither. While a scenario is locked, the status bar shows the Baseline: Locked pill.
Why lock an as-built scenario
On an as-built scenario the baseline is the record of the site — the answer to “what does this site actually look like right now”, which other people and tools trust as ground truth. Locking it means routine edits can’t accidentally overwrite that record. Day-to-day changes belong in recording mode (see above), which adds to the history without touching the baseline, and needs no unlock; the lock refuses a design edit and leaves recording open.
When unlocking is the right call
To edit a locked scenario, click the Baseline pill and confirm. The unlock is yours alone: the scenario stays locked for everyone else. Use it for a one-off change; to open the scenario to everyone for good, remove the lock instead.
On an as-built scenario, unlock the baseline when you need to correct a mistake in the record — for example, a control point that was entered with the wrong elevation, or an entity that was never actually built the way the record shows. That’s a genuine correction to what the record says existed.
Unlocking is not the right tool for routine edits — those belong in recording mode (to log what’s happening on the site) or in a hypothetical scenario (to plan a change before it happens). If you find yourself unlocking often, that’s usually a sign the edit belongs in one of those places instead.
It doesn’t stay unlocked
An unlock is deliberately short-lived. The scenario automatically re-locks when you close the site, when you switch modes, branches, or scenarios, when the clock leaves Live, and after about ten minutes without a change — so an unlock you forgot about doesn’t linger.
Unlocking is offered in design mode only, so correcting a record is a deliberate two-step move: switch to design mode, then unlock. In recording mode the padlock is there to tell you the state, not to be clicked.
Continue Learning
| Core Concepts | Sites, scenarios, entities, and coordinates |
|---|---|
| Scenarios | Compare design alternatives side by side |