Skip to content

Core: Allow TOML documents for player files - #6362

Draft
duckboycool wants to merge 2 commits into
ArchipelagoMW:mainfrom
duckboycool:player_tomls
Draft

Core: Allow TOML documents for player files#6362
duckboycool wants to merge 2 commits into
ArchipelagoMW:mainfrom
duckboycool:player_tomls

Conversation

@duckboycool

Copy link
Copy Markdown
Collaborator

What is this fixing or adding?

Probably a longshot on this being desired, but I feel like there are some pretty big problems with YAML that may make this easier in the long run.
As player files are already meant to at least mostly work with JSON, this can largely just be dropped in. The biggest concern probably is that TOML does not have a null value or something that otherwise maps well to python None, even though some things do use that. I've done a bandaid fix for trigger categories here to use the string "null", but this may not work everywhere. Even though I think it'd make sense to use it there as well, this would make translating the host.yaml trickier in addition to the work needed on supporting it on Group and such already.
Since there's now conflicting formats, I think this now necessitates extension checking for local gen. I also figured it makes sense to handle json specifically so people will know if their file that was meant to be a json is only actually valid as a yaml.

If we do actually want to do this, I think rollout should probably follow something like the following:

  1. Merge just the functionality for reading player files (it'd probably also be worth doing some more cleanup around this) and leave it undocumented for now.
  2. One release after being introduced (once it can hopefully get some testing in practice), work out any of these issues and then add it as an optional alternative for templates, option exports, maybe the settings file, etc. Add explanations for using it to the relevant guides, possibly as the recommended.
  3. At some point possibly switch it out to be default. I doubt we'll ever want to actually deprecate YAML support, but I guess we could if it really becomes ubiquitous.

Also, since we don't write anything for now, we could probably get away with the standard tomllib. I think we could want to in the future though, and the functionality here to keep the state of the document intact when reading could be beneficial for things like the host config. I also think it'd be good to introduce this with TOML 1.1 support, which would have to wait until python 3.15 for stdlib. (Plus the dependency is pure-python and quite light.)

How was this tested?

Tested local and webhost gen with the following player yaml toml. Also tried to make sure some error cases were still handled sensibly.

# Top level values.
name = "TOMLQuest{player}"
# Here's a way that you can do weights.
game.APQuest = 10
game."A Hat in Time" = 5 # Names with things like spaces will need to be quoted.
quantity = 10

[APQuest]
# Alternate weights method. These keys are strings, so like json, this could run into ambiguity for things that can take
# string keys or another type. (The non-inline style relies on TOML 1.1)
progression_balancing = {
    10 = 10,
    90 = 10,
}

["A Hat in Time"]
# Empty game section.

[[triggers]]
# Arrays of tables actually work out pretty nicely with things like triggers, except for not being able to represent
# null natively.
option_category = "null"
option_name = "game"
option_result = "A Hat in Time"
[triggers.options.null]
name = "A TOML in Time {player}"

If this makes graphical changes, please attach screenshots.

👨🇱

@duckboycool duckboycool added the is: enhancement Issues requesting new features or pull requests implementing new features. label Jul 29, 2026
@github-actions github-actions Bot added affects: core Issues/PRs that touch core and may need additional validation. affects: webhost Issues/PRs that touch webhost and may need additional validation. labels Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

affects: core Issues/PRs that touch core and may need additional validation. affects: webhost Issues/PRs that touch webhost and may need additional validation. is: enhancement Issues requesting new features or pull requests implementing new features.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant