A Maquina Do Tempo

What actually happens when you try to build a working a maquina do tempo

Most people who start a time simulation project have no idea where to begin. They jump straight into trying to model the physics without understanding what they're actually trying to simulate. Here's what I learned after building three different versions over the past few years.

The core problem nobody talks about

A real a maquina do tempo isn't a single piece of code. It's a stack of interconnected systems - input handling, state management, timeline rendering, and the actual temporal logic layer. The mistake everyone makes is treating it as one monolithic script. That doesn't work. You need separation of concerns from day one. I spent six weeks debugging a version where the timeline renderer was fighting with the input handler over the same data object. The clock would drift backwards during heavy user interaction, which is the exact opposite of what you want. The fix was straightforward once I stopped trying to be clever: I created a read-only snapshot of the state that the renderer consumed every frame, completely decoupled from the write operations happening in the simulation layer.

Setting up the foundation

Start with a simple timestamp system. You don't need anything fancy. A Unix epoch millisecond value stored in a structured object is enough for 90% of use cases. The common pitfall here is trying to use JavaScript Date objects for arithmetic. They're notoriously unreliable when you're doing anything beyond basic manipulation - daylight saving time transitions, timezone edge cases, and leap seconds will silently corrupt your data if you're not careful. My approach is to store everything as a single integer representing milliseconds since epoch, then wrap it in a tiny helper class that exposes only the methods I actually need. Things like addOffset(), toHumanReadable(), and compare(). That's it. No timezone calculations unless the user explicitly requests them.

The timeline engine

This is where most projects die. The timeline engine is responsible for taking your temporal data and presenting it in a way that's actually usable. You need to decide early whether you're building a linear viewer, a branching narrative tool, or something more complex like a parallel universe explorer. For a basic a maquina do tempo implementation, I recommend starting with a linear timeline with jump points. Users can add events at specific timestamps, then jump forward or backward by clicking. The branching complexity comes later when you have that working solidly.

The rendering layer should use a canvas or SVG approach rather than DOM manipulation. I tried the DOM route first with individual div elements for each event, and performance tanked once you had more than a few hundred entries. Canvas handles thousands of events without breaking a sweat. The tradeoff is that interactions become slightly more complex to implement, but you should be using a proper event routing system anyway rather than native click handlers.

State persistence

Don't underestimate this part. Every version I've built has crashed or been accidentally closed at some point. Your data needs to survive that. The minimum viable solution is automatic saving to localStorage every time the state changes, plus an explicit export function that writes a JSON file. I also layer in IndexedDB for larger projects because localStorage has a hard cap around 5MB depending on the browser. If someone is building a serious timeline with hundreds of events, they'll hit that limit faster than you'd expect. IndexedDB adds minimal complexity and removes that ceiling entirely.

Where it actually breaks

Here's the honest part that nobody puts in tutorials: temporal simulation tools have a hard limit around what they can reasonably handle. When you start modeling causality chains - event A causes event B which causes event C - the computational complexity grows exponentially. A simple causal chain of five links is fine. Ten links and you're already seeing significant slowdowns in the browser. Fifteen and the thing becomes practically unusable without a dedicated backend. Another limitation that catches people off guard: concurrent timeline editing. If two users are editing the same timeline simultaneously, you need conflict resolution. I've seen too many projects ignore this and just do last-write-wins, which means half the edits disappear silently. If you're building a collaboration feature, look into CRDTs or at least operational transforms. It's not trivial to implement correctly.

Alternatives to consider

If your goal is simply to track events in chronological order without the temporal manipulation features, there are plenty of mature open source options like TimelineJS or even spreadsheet-based approaches that will save you weeks of development time. An a maquina do tempo is worth building only if you specifically need the forward-and-backward jumping, causality modeling, or branching timeline features that these tools don't provide. For a downloadable starting point, the community template on GitHub has a working skeleton with the decoupled state architecture I described. It handles basic timeline rendering and import/export. The code is messy but functional, and it'll save you the first three weeks of figuring out where to put things.

The one thing I wish I'd known

The UI is easier to build than the data layer. Everyone gets excited about making it look good and interactive. But if your underlying data structure can't handle the operations you need, no amount of polish will save it. I'd recommend spending at least half your total development time on the data model before you write a single line of UI code. The rest will be significantly less painful. Build it slowly. The version you ship will be flawed, and that's fine. The next version will be better. Just make sure the data survives between versions.