Damage Reports

Hi Gang. Happy Thorium Thursday.

Recently I took a break from building Legacy mode to finally finish the damage report and repair system that I outlined earlier. Looking back, it's been in the works for about 5 months, so it's about time I finish it.

It's taken this long because, as it turns out, damage reports are timelines. And timelines in Thorium Nova are complicated. If you're not familiar, timelines are the primary tool for automation in both Thorium Classic and Thorium Nova. In Classic, timelines are just a linear set of actions that the Flight Director can execute at the right moment. They're a great way to encode the different story beats of a mission - things like adding sensor contacts, sending long range messages, and changing the viewscreen. If you know that a certain action will happen at a certain time during the mission, timelines are huge time savers.

Thorium Nova expands this in several important ways that were impossible in Thorium Classic. First, it supports fully automated timelines through "Checks", which look at the state of the simulation and evaluate some condition. Timelines can have checks for events firing with certain parameters, whether two entities are a certain distance from each other, or if an entity's properties meet some condition. When the condition is met, more actions can be activated, which includes advancing the timeline and performing whatever actions are in the next step.

This adds a lot of power, but also a lot of complexity, which I explain in the linked blog post above. It essentially turns writing timelines into a programming language, where you can put values into variables, perform operations on them, and write control flow logic. The last 5 moths have been spent researching how to do that in a sensible way. I've explored writing it out as a script with actions and checks sprinkled in, I've played with having timeline authors actually write TypeScript code. What I settled on is a block-based approach, where each block does one simple thing, like putting a value in a variable, and then moves on to the next block. I've tried to make it as intuitive as possible, but I'm certain it will be adjusted slightly as people play around with it.

An in case this makes you really nervous, don't worry - the old Classic mode of just putting actions in your timelines is still totally valid. You don't have to worry about any of the complicated blocks if you don't want to. But all of these things will be well documented so you should be able to pick it up for your own timeline writing.

Once I felt satisfied with the process of writing timelines in general, I could turn my attention back to damage reports. It turns out they have some special requirements:

• A way to indicate that the timeline is complete so the damage metrics improvements can be applied.
• A method for filtering timelines based on some criteria
• Some way to display the instructions of the report.

For the first requirement, a simple "Auto-apply Damage Metrics" checkbox provides some configurability. When checked, the timeline writer just has to make sure that the last step of the timeline includes an "Advance Timeline" block. When the timeline advances past its last step, it is considered "Completed" and will apply the damage metrics. Otherwise, a "Complete Report" timeline action can be used for situations where you want to more explicitly repair the system as part of your timeline. This gives flexibility for folks who want more sophisticated reports timelines that include branching or parallel timelines.

For filtering timelines, I figured since blocks are a convenient way of expressing logic, we might as well use them to decide whether a report should be used. A special "Timeline Availability" block is exclusively used in timeline prerequisites to say if that timeline should be available. In the example above, we're checking to see if a variable called $systemType matches the text shields.

The prerequisites run for all timelines whenever we are generating a new damage report, so it's not necessarily a good idea to put actions in these blocks. But you can if you want. Running all the prerequisites gives us a list of available timelines, and then one is selected at random.

But where is that $systemType variable coming from? Since this timeline is a report, Thorium Nova provides the $systemType of the system that is being repaired as a variable automatically. In fact, there are many variables which can be used in blocks and descriptions.

Which brings us to the report instructions. Those come from the descriptions of each step, which now support variable interpolation - inserting variables into text where you want them. The interpolation engine is sophisticated enough for most purposes, and will be fully documented. It works by first executing all of the blocks for that step, which might initialize some variables that will be necessary for the description. It then generates the description and provides it to the crew so they know what to do for their damage reports.

Note that this report just runs a macro and then advances the timeline in response to that macro. But where does it run that block inside the macro? We wouldn't want to advance the timeline immediately, especially if its in response to some check inside the macro. Lets take a look again.

In the middle, you can see the Wait until... check. We don't want to advance the timeline until that check is complete. Which is why, at the bottom, there is a special block called Macro Slot. It basically says "The timeline that runs this macro probably wants to run something as part of this check. Let's do that here." This is an exceptionally powerful feature for macros - making it easy to encapsulate behavior while allowing the timelines that use macros to still perform actions within the macro.

---

That's it for writing reports. Again, I'll be sure to document all of these behaviors when we've done some tests and solidified the design.

Now lets take a look at the process of generating and performing damage reports. It starts with diagnostics, which allow a crew to determine the status of individual systems.

There are four levels of diagnostics. Level 1 diagnostics will just provide information about a system. Level 2, 3, and 4 diagnostics will provide 1, 2 or 3 possible repair options respectively. However, it takes exponentially longer to do higher levels of diagnostics. And while it is possible to do concurrent diagnostics for different systems, each additional diagnostic slows down all the others. So crews will have to be judicious about the level and number of diagnostics they perform.

When completed, the diagnostic provides the damage metrics for the system. This gives the crew some choice both in what systems they fix and how they fix it. They can then choose which metric to fix.

Each damage report candidate addresses a different type of damage, and you can see how each will affect the damage metrics. In fact, some reports affect other systems. And some even have negative impacts as well as positive.

This shows the benefit of doing Level 4 diagnostics - it gives the crew a better chance of getting a really good report that improves the system metrics the most. They can then choose a report and begin working on it.

And now the crew can do the actual report. Note how the variables from the macro have been inserted into the damage report instructions - the system name and a randomly generated remote access code. And believe it or not, when we type in that remote access code, the report progresses and completes, which automatically applies the damage metric improvements - all without any Flight Director involvement.

---

I'm really pleased with how all of this has worked out. It's fully automated, but still allows for the manual style reports from Thorium Classic (just a report with directions but no blocks). Or maybe you want to do the opposite, where damage report instructions are not shown on a damage reports card, but provided by NPC crew members on the ship via inter-ship messaging (which I've already completed as part of my Legacy mode work) - that's totally possible.

I'm certain there are lots of bugs and user experience issues to shake out, but this provides a great foundation that gives the crew agency and enables flight automation without taking away from the Flight Director's power or options.

If you're interested in writing damage report timelines for Thorium Nova, let me know. It's the kind of thing that I would love the community to be involved in, since I'm certain all of you have great ideas for novel and interesting damage reports. We probably won't start working on reports until more of the controls are done (we kinda need things like software panels, damage teams, and exocomps so crews actually have more than remote access codes to fix things). But even still, I'd love to hear your ideas.