Most speedrun games or obbies rely heavily on a roblox custom stopwatch script to keep players competitive and engaged. It's one of those core mechanics that seems really straightforward until you actually sit down to code it and realize you need to handle decimal precision, string formatting, and UI updates all at once. If you're trying to build a racing game or just want to see how fast someone can finish your obstacle course, having a timer that actually looks good and runs smoothly is pretty much non-negotiable.
In this walkthrough, we're going to build a stopwatch from the ground up. We won't just dump a wall of code; we'll talk about why we're doing things a certain way, like why os.clock() is usually a better choice than a simple wait() loop for keeping time.
Setting up the UI for your stopwatch
Before we even touch a script, we need a place for the time to show up. You can't exactly have a stopwatch if the player can't see the numbers ticking away.
Head over to the StarterGui in your Explorer window. Add a ScreenGui and call it something like "TimerGui." Inside that, add a TextLabel. This is where the magic happens. You'll want to spend a minute or two making this look halfway decent. Pick a monospaced font if you can—something like "Roboto Mono" or "Courier"—because it keeps the numbers from jumping around as they change. If you use a variable-width font, the whole label might shake every time a "1" changes to an "8," and that's just annoying to look at.
I usually position mine at the top center of the screen, maybe give it a semi-transparent background, and set the text to "00:00.00" as a placeholder. Once you've got it looking the way you want, we can get into the actual logic.
The logic behind the roblox custom stopwatch script
The heart of any roblox custom stopwatch script is the way it calculates elapsed time. You might be tempted to just create a variable called seconds and add 1 to it every second using a while true do loop. Please don't do that. wait(1) isn't perfectly accurate; over a few minutes, your timer will start to drift and become out of sync with reality.
Instead, we want to use os.clock(). This function returns the amount of CPU time used under the hood, but for our purposes, it's a super precise way to get a timestamp. By grabbing the time when the player starts and comparing it to the current time, we get an exact measurement of how long has passed, down to the millisecond.
Creating the LocalScript
Since the UI is local to the player, it makes the most sense to run the timer on the client. Add a LocalScript inside your TextLabel. Here's a basic way to structure the code:
```lua local label = script.Parent local running = false local startTime = 0
local function updateTimer() while running do local currentTime = os.clock() local elapsed = currentTime - startTime
-- We'll add formatting here in a second label.Text = tostring(math.floor(elapsed)) task.wait(0.05) -- Update frequently enough to look smooth end end ```
This is just the skeleton, though. If you run this, you'll just see a bunch of raw seconds, which isn't very helpful for a "custom" look.
Making the time look pretty
Nobody wants to see "124.5783921" on their screen. We want minutes, seconds, and milliseconds formatted nicely. This is where string manipulation comes in. We can use math.floor and the modulo operator % to break that big "elapsed" number into smaller chunks.
Here is a much better way to format the text inside your loop:
```lua local minutes = math.floor(elapsed / 60) local seconds = math.floor(elapsed % 60) local milliseconds = math.floor((elapsed % 1) * 100)
label.Text = string.format("%02d:%02d.%02d", minutes, seconds, milliseconds) ```
Using string.format is a total lifesaver here. The %02d part basically tells Roblox: "Hey, make sure this number is at least two digits long, and if it's not, put a zero in front of it." That's how you get "05:01" instead of "5:1."
Adding Start, Stop, and Reset triggers
A stopwatch that just runs forever from the moment you join the game is kind of useless. You need a way to trigger it. In most games, this happens when a player touches a part.
You could set up a "StartPart" and an "EndPart." When the player touches the StartPart, you fire a RemoteEvent or simply toggle a boolean if you're doing everything locally. Let's say you want to use a button on the screen just to test it out. You could add a "Start" button and connect it like this:
```lua local startButton = script.Parent.Parent.StartButton -- Adjust path as needed
startButton.MouseButton1Click:Connect(function() if not running then startTime = os.clock() running = true updateTimer() end end) ```
To stop it, you just set running = false. Simple as that. The loop stops, the startTime stays where it was, and the display freezes on the final time.
Why precision matters in speedruns
If you're making a serious competitive game, players are going to obsess over milliseconds. Using task.wait() instead of the old wait() is crucial because task.wait() is synced with the Roblox task scheduler and is much more reliable.
However, even with task.wait(), you shouldn't rely on the loop's speed to "count" the time. Always, always calculate the time based on the difference between the current os.clock() and your startTime. That way, even if the player's computer lags for a second and the UI stops updating, when it recovers, the time will "jump" to the correct spot instead of being a second behind.
Handling the server-side
While your roblox custom stopwatch script lives on the client for the sake of a smooth UI, you can't really trust the client if you're planning on having a global leaderboard. Exploiter-level players can easily change their local scripts to report a finish time of 0.001 seconds.
If you're worried about cheating, you should also track the time on the server. When the player touches the start line, tell the server "Player A started now." When they hit the finish, the server checks its own clock. If the server says they took 10 seconds but the client claims they took 2 seconds, you know something fishy is going on.
For a casual obby, though? Running it all on the client is totally fine and keeps things responsive.
Customizing the look and feel
Since the keyword is "custom," don't be afraid to get creative with how the timer behaves. You could make the text change color as the player gets closer to a "Gold Medal" time. Maybe the text pulses or grows slightly larger when they hit a new personal best.
You can also add a "split" system like you see in professional speedrunning software. Every time a player passes a checkpoint, you can display a small ghost-text of their previous best time at that spot. It's these little touches that make a roblox custom stopwatch script feel like a part of a polished game rather than just a quick coding exercise.
Troubleshooting common issues
One thing that trips people up is the timer not resetting properly. If you start the timer, stop it, and then start it again without resetting startTime, the "elapsed" time will include the time that passed while the timer was stopped. If you want a "Resume" feature, you'll need to track "TimeSpentBeforePause" and add it to the calculation. If you just want a fresh start, always make sure startTime = os.clock() happens right when the "Start" logic kicks in.
Another issue is the UI flickering. If you update the timer too fast (like every frame using RenderStepped), it might be overkill and hit performance on lower-end mobile devices. task.wait(0.05) or 0.03 is usually the sweet spot where it looks fluid to the human eye but doesn't set anyone's phone on fire.
Building a roblox custom stopwatch script is a great project because it covers UI, logic, and string formatting all in one go. Once you've got the basics down, you can expand it into a full-blown racing system or a time-trial challenge that keeps players coming back to beat their own records. It's all about making those numbers feel meaningful!