RFC: Config.ron Specification

[amethyst]

RFC: Config.ron Specification

[lschmierer]

Alternatively, addional settings in config.yaml could be ignored or even deleted if a dedicted config file is specified.
So a property can only be defined in one place. This might be better. (Simpler to understand where property is defined.)

Another proposal

Another way would be to automatically look for a dedicated config file, if a config can not be found in config.yaml.

For example:

In this case the properties from config.yaml are evaluated:

config.yaml:

logging:
    file_path: "new_project.log"
    output_level: warn
    logging_level: debug
display:
    brightness: 1.0
    fullscreen: false
    size: [1024, 768]
title: "My coolest game"

While in this case, a file display.yaml wolud be evaluated, if existent:

config.yaml:

logging:
    file_path: "new_project.log"
    output_level: warn
    logging_level: debug
title: "My coolest game"

If the file display.yaml does not exist, default properties are added to config.yaml.
If display.yaml exists, but properties are missing, missing properties are added to display.yaml.

This might be more straight-forwarded and convenient than my first proposal.

[thiolliere]

I got a repository that might interest you, it contains:

• the code for unifying yaml files
• a trait with a function from_yaml implemented for basic types
• macro to implement the trait for enum and struct.

the macro is the most interesting part, but I failed to parse type so I parse it as an Ident (see the readme and the example)

[White-Oak]

@ebkalderon Also, should configurations for shards be discussed here, And should they even be in the main config.yml. I suggest keeping separate configs for all shards. How do you like it?

[White-Oak]

@ebkalderon me too, but need other opinions.

[White-Oak]

You don't need to have all configs spread, instead you can separate them individually to subfolders. Like, if there is a section that is too verbose and is changed too much, one may decide to separate it into the single file.

And after all, why not? :)

[Aceeri]

I'm thinking of leaving an interconnected configuration system out of this. Instead of having a top-level config, we could just load in a couple different kinds (Renderer, Logging, etc.) and add them possibly as resources to the specs::World.

[Aceeri]

I have the new configuration stuff worked out, just waiting on 1.15.0 for rust so we can use serde_derive. Old amethyst_config crate will be deprecated and the config stuff will be in the main project.

[minecrawler]

@Xaeroxe I think it would be better for overview to deprecate this issue and open up a fresh one with the RON spec in the OP (plus different considerations already done here). Imho, it is quite tedious to check all those posts to see how what can be applied in what way to the new format...

[Xaeroxe]

Lots of baggage here, most of which is no longer applicable, so I'm closing this. If anyone still wants a formal design done here please open a new issue.

[White-Oak]

amethyst/tools#26 is related.

[LucioFranco]

@White-Oak I like the idea of the title attribute

[OvermindDL1]

Why yaml? Good to consider this before it is fairly set in stone.

[White-Oak]

@OvermindDL1 well, why not?
Options are:

• YAML
• JSON
• TOML
• XML (Please, no)
• others?

[ebkalderon]

@OvermindDL1 Good question! See the top of the relevant wiki post for the reasoning behind YAML.

[ebkalderon]

I'm fine with that. The preincluded ones should probably be named project.yml/main.yml/game.yml (need to pick best one) and input.yml. All the others can be <shard name>.yml. Does that sound good?

[LucioFranco]

@ebkalderon I feel like that would clutter the directory with config files

[ebkalderon]

Either way, we need to pick one or the other. Pros and cons from what I see:

1. Keep all shards' config files in separate files at the top of the resources directory.
   • Pros: Simpler to design and implement, each shard can look after its own configuration files instead of parsing a shared monolithic file.
   • Cons: Looks messy in the file browser, core configuration files like input.yml and project.yml are lost in a sea of other files.
2. Unify all shards' configuration under config.yml
   • Pros: Less clutter in the top-level, arguably more convenient for end-users (config.yml for configuration, input.yml for keybindings). Imagine if you were forced to have a separate Cargo.toml for each target in a crate.
   • Cons: Programmatically appending/deleting lines of text is never clean from a design perspective.

[LucioFranco]

@ebkalderon we can always have both. Have a unified api for people who are implementing shards and let the user split up the config file or keep it as one. So small games will have one file and others can separate them into groups.

[lschmierer]

Proposal:

Everything can be put in one file:

config.yaml:

display:
    brightness: 1.0
    fullscreen: false
    size: [1024, 768]

But can also be put in a seperate file using a config field:

config.yaml:

display:
    config: "display.yaml"

display.yaml:

brightness: 1.0
fullscreen: false
size: [1024, 768]

If somebody property is defined in both,

config.yaml:

display:
    config: "display.yaml"
    brightness: 0.5

display.yaml:

brightness: 1.0
fullscreen: false
size: [1024, 768]

we can give one priority over the other (I would prefer config.yaml overrides specialized configs).

[LucioFranco]

@lschmierer I like your second proposal. Seems like that would clean up the directory a lot but still allow flexibility.

[OvermindDL1]

It sounds like what you are trying to design is something like the HOCON configuration. HOCON is backwards compatible with JSON, but with more features, like object keys do not need quotes and you can include other files, supports comments, and more useful features. Unsure if any pre-made RUST library, but there is a C++ one that could be ported and/or used?

[ebkalderon]

@OvermindDL1 I don't know; maybe one of them could be ported. I'd have to look it up some of the libraries and look at the source.

But what exactly is wrong with YAML? It's pretty understandable and familiar to most people, especially for those who have worked with Travis CI, AppVeyor. I know that the standard's complexity is often a huge gripe for people, but since we don't really plan on using its advanced features (tags, variables, etc.) this is not a huge concern for me.

[ebkalderon]

@lschmierer Do you think that title: should maybe go under display:? I don't like the idea of having an entirely new title.yml file being an option. It seems redundant. Perhaps we could rename display to window to make the name match better?

Edit: Sorry, tagged wrong person!

[White-Oak]

@lschmierer I definetily love your second approach. Ecpecially, since it stacks so good with 'Shards' that are being discussed in #34.
The unanswered question is 'Should <name>.yml still include a name of a section or just simply be a sequence of key?'
display.yml:

display:
    brightness: 1.0
    fullscreen: false
    size: [1024, 768]

versus

brightness: 1.0
fullscreen: false
size: [1024, 768]

Updated issue text with 'Sepatate configs' idea proposed by @lschmierer that many liked.

[ebkalderon]

@White-Oak I like the second one better, myself. It seems a bit verbose to repeat the section when the filename itself repeats it.

[LucioFranco]

@White-Oak @ebkalderon I like that second one as well. If there is no parent attribute we just pull it from the file name. 👍

[ogoding]

Reposted from #26 -> Is there a set of options that are guaranteed to be used in any given game? Things like title might not be used (e.g. CLI game).

[thiolliere]

@ogoding it depends of what is in the core engine. If the window creator is a shards then title is not mandatory.

my proposal is:

yaml configuration must be like this:

audio:
  global_volume: 0.5
  music_volume: 1.0
  effect_volume: 0.7
window:
  dimension: [640,480]
  vsyc: true
  multisampling: 8
  fullscreen: false
  inputs:
    ...
event_loop:
  ups: 120
  max_fps: 60
core:
  entities:
    character:
      position: [0.,0.]
      velocity: [0.,0.]
      acceleration: [0.,0.]
      damping: 1.0
      shape:
        type: circle
        radius: 1.0
      color: yellow
    monster1:
    etc..

but we don't want to write it in one file so I propose to extend yaml syntax little:

all yaml file have one document that is an assiociative array

for each key of this array if its value is the string extern file then it search in $key.yml or $key/config.yml

so we split in those file:

/config.yml

---
audio:
 ...
window:
 ...
event_loop:
 ...
core: extern file

/core/config.yml

---
entities: extern file

/core/entities

---
character:
 ...
monster:
 ...

also about what contains the config file:

I think all shards and the core have a key in the root associative array. And the core must have an entities key.

[XAMPPRocky]

@thiolliere Would it not be more intuitive to follow Rust's module system?

resources/
    config/
        config.yml
        window.yml
        audio.yml
        entities/
            entities.yml
            character.yml

[thiolliere]

@Aaronepower yes that's the idea. but in my example I put entities in core module and window and audio directly in config.yml (as you can declare module in a file in rust).
so my example result in:

ressources/
    config/
        config.yml // contain module audio and window
        core/
            config.yml
            entities.yml

And you're right it will be more intuitive if we stick to rust's module system

[Aceeri]

#61 should be solving this. It uses a kind of rust-module like path

config/
    config.yml
    display.yml   # Can be defined this way
    display/      # Or this way
        config.yml

# config.yml
title: "Amethyst Game"
display: extern

# display.yml or display/config.yml
brightness: 1.0
fullscreen: false
size: [1024, 768]

I didn't love the idea of having it be able to be set in both the config.yml and display.yml, since that would be rather annoying. For instance, thinking you have modified something, only to find out you were in the wrong file. However, the directory display/ has priority over display.yml. Maybe there should add some sort of warning that there are two of the same field.

[White-Oak]

@Aceeri I suppose that local files (as in display/config.yml) should have priority, but you should be able to set variables in both of the places. A warning about setting some variable in various places would be nice in this situation.

[XAMPPRocky]

@Aceeri Should you not provide an error if there is multiple implementations, over implicitly prioritizing an arbitrary placement?

[Aceeri]

@Aaronepower I'm thinking of having display/config.yml should be prioritized if there are multiple, but also output a warning/error similar to the errors given if it cannot find a value or the value is the wrong type in the .yaml file. I don't love the idea of a hard error (panicking) in configs since it can easily be recoverable by either using the defaulting values.

[ebkalderon]

Do we really need to have the resources/display/config.yml option? I don't think that a complete Rust module-like system is really feasible for configuration files, since it will add a lot of unnecessary complexity. For example, how would we determine the order in which sub-config files are loaded and how would handle conflicts between them in a recursive manner? Assuming we are mimicking Rust module layout, this means we would need to support nested subfolders with multiple files inside of each. Is this really needed? Seems like it would also make game projects far less organized since the configuration files are now scattered across many different locations.

I think we should stick to simplicity and minimal overhead at startup here and only support the three use cases below:

1. Monolithic config file
   • config.yml
2. Some config sections split into separate files, e.g. if a particular section is too long or verbose
   • config.yml + input.yml
3. Everything in a separate file and there is no config.yml at all
   • input.yml + display.yml + logging.yml + ...

To me, this is still reasonably flexible and seems much easier to implement. Does this seem like a reasonable approach for us to pursue?

[Aceeri]

@ebkalderon I'm doubting there will be much use at all of the sub-folder for configs in the engine, but
I'm thinking that it should be possible to use the amethyst_config for ingame purposes as well, not just solely for the engine.

For instance, in a game you could have some monster configuration folder holding configurations that could be used as a guideline for adding different components in the ecs.

Loading order isn't much of a problem, I just do it depth first and if there are conflicts, the value defaults and displays a warning/soft error in the console.

[ebkalderon]

@Aceeri I think there may be some confusion regarding the purpose of these configuration files. I think you might be mistaking them for prefabs, which are reusable templates for making entities or components. Those should be placed in the resources/prefabs/ folder and would indeed benefit from depth-first nesting for organization purposes, like you suggested.

In contrast, configuration files should only be used for configuration, whether engine or gameplay-side (e.g. difficulty settings or other game-specific switches). I feel like supporting arbitrary files and nesting for configuration files would make game projects very messy, very quickly.

I feel that the parsing of ECS prefabs and entities is outside the scope of amethyst_config IMO. Anyway, I hope I am making sense; I'm writing this half asleep right now. 😄

[Aceeri]

The guideline for components thing was just an example. There are plenty of other reasons for multi-nested configs that aren't exactly necessary in the engine. Besides, it shouldn't hurt to have an additional feature like this.

[ebkalderon]

Well, I guess you're right, it really doesn't hurt at all. But even so, could you perhaps name a use case as an example? The point of configuration files is for defining simple key-value settings, and wouldn't it be much more user-friendly to just have configuration file(s) easily accessible at the resources root instead of spread about in subfolders, much like other game engines do? Plus, the validation of game projects by the build tool is much easier since it doesn't need to search recursively through arbitrarily-named directories.

[ebkalderon]

@White-Oak Yes, I agree that configuration files should optionally be separable into multiple files, however I disagree on the point of being able to put them in arbitrary nested sub-folders. Why not leave them at the root of the resources folder? Having to hunt through directories, with the structure likely differing from game to game, to find configuration files is not very appealing to me.

[lschmierer]

I have the new configuration stuff worked out, just waiting on 1.15.0 for rust so we can use serde_derive.

@Aceeri Already started implementing somewhere?

Edit: Sorry, didnt see #152

[Aceeri]

Do we still want to go ahead with that interconnected semi-monolith/semi-module config.yml or just have it spread out into multiple files for different configuration types? Like DisplayConfig would be in a DisplayConfig.yml file in the configurations directory, and LoadingConfig would be in LoadingConfig.yml?

[Xaeroxe]

Conversation at: #171 became a duplicate of a lot of stuff said here. Perhaps we ought to close #171 and continue that discussion on this thread.

[Xaeroxe]

Ron is ready to use at this point and we've decided in other threads that's what we're going to be using, so I changed the issue title.

[torkleyy]

Agreed. If somebody wants to summarize, I'll close this one.