Implement Custom Variables

[CryZe]

This Pull Request adds custom key value pairs to Runs. They can be created by the runner in the Run Editor and can store arbitrary string based values that the runner wishes to store with the splits. Components can then use these variables to visualize them. In particular, the text component can visualize these variables as key value pairs. Variables can also be provided by auto splitters, components or through other means. The automatic variables are temporary in nature and are therefore never stored in the splits files. The user also can not edit them. There also is an orthogonal scope per variable that binds the variable's value only to single attempts and resets its value between each one. This can be useful for per attempt counters.

Closes #200

• Rough prototype
• Settings for text component
• Saving custom variables
• Loading custom variables
• Adjustments based on proposal
• Run Editor UI in LiveSplit One
• Documentation
• Tests

[CryZe]

Proposal

After experimenting with the implementation of the Custom Variables, here's a final proposal of how they possibly should work. I'll adjust the final implementation based on what we decide here.

Variable Kind

There are two kind of variables: Temporary or Permanent.
A permanent variable is always stored in the splits file and is never removed unless the user explicitly removes it via the Run Editor. If a transition to a different kind of variable is perceived, only certain transitions are allowed: A permanent variable can never become a temporary one, while a temporary variable can become a permanent one. If a variable is manually created in the Run Editor, it is always considered permanent. If the variable is created via a script, it is considered temporary by default, unless otherwise stated. The Run Editor only shows permanent variables. Creating a variable in the Run Editor that is already a temporary variable keeps its value.

Variable Scope

A variable's value has one of the following scopes: Always or Per Attempt. These can be extended to other values in the future, such as Per Segment or Per Runner but the MVP is only implementing these. The scope defines when a variable has a value. Variables that are scoped to a single attempt can only have a value during an attempt and the value automatically gets removed once the attempt is over. The value of an attempt scoped variable is not stored in the splits file and is not shown in the Run Editor.

[CryZe]

@wooferzfg I'd like you to read through the proposal and want your opinion on it.

[CryZe]

I almost feel like we should have design documents for every major design decision we do. And then have a test per sentence, that actually references the sentence of the design document. Not sure how those would interact with module and doc comments then though. I guess I'll see if I can fit the proposal fully into doc comments and module documents. If that works out, then there might not be a need for separate design documents.

[wooferzfg]

• What's the functional difference between Temporary and Permanent variables? Is it just that Temporary variables don't show up in the Run Editor?
• Do we ever have a case where a Permanent variable is scoped Per Attempt? I can see where a Permanent variable would be scoped Per Segment (to save some sort of custom info), but Per Attempt seems inherently temporary to me. Also, "The value of an attempt scoped variable is not stored in the splits file and is not shown in the Run Editor" sounds like it's describing a Temporary variable.
• Even though we have an Always scope, I'm assuming that variables are saved per splits file. If so, we should consider the expected behavior when switching between splits files. What should components show if the variable it was displaying no longer exists?

[CryZe]

What's the functional difference between Temporary and Permanent variables? Is it just that Temporary variables don't show up in the Run Editor?

Temporary variables are usually provided by auto splitters and other scripts. So they are mostly statistical in nature and don't need to be saved. This also means you don't usually want to edit them or create them yourself.

Do we ever have a case where a Permanent variable is scoped Per Attempt?

Mmh, I'd say that you create a death counter variable in the run editor, make it per attempt scoped and then it resets between attempts. However now that I'm thinking about it, we may not actually need to create it in the run editor. Just the layout settings or whatever might be sufficient.

However more permanent counters would be created via the run editor, so maybe it is worthwhile having the notion of a permanent variable with a temporary value regardless, which is the whole idea behind the separation of the two terms here. (The terms can change if you come up with better names)

What should components show if the variable it was displaying no longer exists?

The text component for example simply shows a dash, just like other key value pair components (info text components) do. But yeah components that use variables need to be able to handle them not existing / having a value.

[wooferzfg]

Per Attempt and Per Segment kinda seem like different types of scope to me. Per Attempt describes a one piece of information that gets cleared when out of scope, while Per Segment describes multiple pieces of information that are limited to each segment but don't actually get cleared (at least in the case of Permanent variables?).

[CryZe]

No, they would get cleared the same way, but they could be stored in the segment history before being cleared. But every other variable could as well. So I don't think there's a fundamental difference there. Unless I'm misunderstanding what you are saying.

[CryZe]

Maybe we should keep the notion of the scope out of this PR as this is really about the automation of when the variable should be cleared. But maybe that's something that individual scripts / components should decide themselves. Like setting the death counter to per attempt / per segment or whatever in the counter settings (not sure if it will be a component or whatever yet, but no matter what it will be, it will have settings)

[CryZe]

@wooferzfg Considering this is mostly just blocked on the Run Editor changes in the web LiveSplit One, and you seem to actively make changes to that codebase, I'd appreciate if you'd pursue this next, if you want to. I need to check what the state of this is on my side (especially since I already had half of the changes in LSO, so you can probably just pick up that branch).

[wooferzfg]

Yeah, I can definitely work on this. We should talk about the UI design for these changes though.

[CryZe]

@wooferzfg It probably makes sense to push to the branch in my PR instead of on the branch in this repo. (As you can see none of your changes show up as part of this PR).

Also in general when you are working on your own PRs, I'd rather prefer if you worked in a fork. The problem is when people fork the repo, they get a full snapshot of all the branches in it, which means they have a bunch of in-progress branches in their fork, that forever stay in-progress like that. I'd like to just have the master branch here (though dependabot sometimes creates a few branches here too, which I also don't like).

[CryZe]

Not sure why CI is not running anymore?! Maybe it'll start after rebasing again.

Well they work again 🤷‍♂️