[2.0.72] ItemPrototype:fuel_categories

[thesixthroc]

This API would mirror RecipePrototype:additional_categories (or any replacement for this API in 2.1) RecipePrototype:categories.

The heating entity in the Cerys mod consumes only solid fuel. For this to work, solid fuel is changed to a new fuel_category "chemical-or-radiative", and that FuelCategoryID is then added to the fuel_categories of many different BurnerEnergySource.

If another mod similarly wants to give special behavior to solid fuel, the only way to implement is to use more cascading `-or-`s, e.g. `chemical-or-radiative-or-solid`, causing ‘incompatibility by default’ similar to recipe categories earlier in 2.0.

[protocol_1903]

+1

[safthelamb@gmail.com]

+1 with it being `fuel_categories` to follow the precedent set by 2.1

[Powerscooter]

+1 for fuel categories. There is quite the load order war going on between mods to ensure their fuels are used correctly. Currently very popular mods declaring own fuel categories include Cerys, Muluna and Maraxsis.

This very much mirrors the crafting categories issue where it'd end up being a very long x-and-y-and-z string in practice.

[MeteorSwarm]

+1. This is such an important issue to fix that I would be okay with breaking existing mods marked as compatible with 2.1 to fix this issue before 2.1 is declared stable.

[wanda-phi]

I would like to shed some more light on the underlying problem. There are multiple issues and pitfalls here which interact and cause compatibility issues between mods.

The general sequence that leads to trouble is:

1. A mod wants to add a new burner device that will only accept one kind of existing fuel in particular (for the sake of example, the Cerys radiative heating tower that only accepts solid fuel)
2. Since accepted fuel depends solely on the fuel_category of the burnable item, and solid fuel belongs to the rather large chemical fuel category, the only way to accomplish that involves modifying the vanilla fuel_category
3. The mod thus swaps the fuel_category of solid-fuel to a newly-added fuel category (for the sake of example, chemical-or-radiative), in data-updates or maybe data-final-fixes
   v The mod adds its new burner device accepting only the chemical-or-radiative category
4. The mod walks through all EnergySource fields on prototypes, looks for entities accepting the chemical category, and adds chemical-or-radiative to their list of accepted categories; this is usally done in data-final-fixes

This can be made to work if only one mod is doing it for a particular fuel. However, if two different mods try to add a solid-fuel-only machine, and they pick different names for the new fuel category, one of them will naturally break the other's new burner by overwriting its changes to the fuel item. In particular, in the above example, note that the other hypothetical mod would be unlikely to use the same chemical-or-radiative name for its fuel category).

Now, from a brief survey I have done on (mostly) planet mods, here's a few real mods doing this dance:

1. planet-muluna:
   • wants to have vehicles on muluna only accept pre-oxygenated fuel, which is considered to be rocket-fuel and nuclear-fuel from the base game
   • in final-fixes:
     • adds a fuel category of muluna-nuclear-chemical-fuel
     • grabs the current fuel categories of nuclear-fuel and rocket-fuel to a local variable
     • changes category of both rocket-fuel and nuclear-fuel to muluna-nuclear-chemical-fuel
     • mutates energy_source of all prototypes to add muluna-nuclear-chemical-fuel wherever previously-stored rocket-fuel's or nuclear-fuel's fuel category is accepted
2. maraxsis:
   • wants to have the diesel submarine accept only rocket fuel (plus a few other items that are not fuel in the base game)
   • wants to have the nuclear submarine accept only nuclear fuel (plus uranium fuel cell)
   • in final-fixes:
     • adds fuel categories of rocket-fuel and nuclear-fuel
     • changes fuel category of both rocket-fuel and nuclear-fuel items to the respective single-item categories
     • mutates energy_source and burner of all prototypes to add the two new categories wherever chemical is accepted
3. Cerys-Moon-of-Fulgora:
   • wants to have the radiative heating tower only accept solid fuel
   • in data: adds fuel category of chemical-or-radiative
   • in final-fixes:
     • changes fuel category of solid-fuel to chemical-or-radiative
     • mutates energy_source of all prototypes to add chemical-or-radiative wherever chemical is accepted
4. Age-of-Production:
   • wants to have the biomass reactor accept only nutrients, biomass, and spoilage as fuel
   • in data:
     • adds fuel category of aop-spoilage
     • changes fuel category of spoilage to aop-spoilage
   • in final-fixes: mutates energy_source of all prototypes of types expected to contain energy_source to add aop-spoilage wherever chemical is accepted
5. lignumis:
   • wants wood to only be accepted by a subset of burners, while keeping other chemical fuels accepted by all of them
   • in data: adds fuel category of wood
   • in data-updates:
     • changes fuel category of wood to wood
     • mutates energy_source and burner of all prototypes of 6 specific types (boiler, reactor, car, locomotive, generator-equipment, burner-generator) to add wood wherever chemical is accepted
6. smoker:
   • wants its new stone-smoker machine to only accept wood as fuel
   • in data:
     • adds fuel category of smoking-chemical
     • changes fuel category of wood to smoking-chemical
   • in data-final-fixes: mutates energy_source of all prototypes to add smoking-chemical wherever chemical is accepted

To start off, we have two obvious compatibility problems here that are unfixable without writing explicit per-mod-pair compat code:

1. maraxsis and planet-muluna changes directly conflict with one another, by stomping on what the final category of *-fuel will be. By sheer luck of load order and the way muluna code is written, the end result is that muluna's changes prevail, but both diesel and nuclear submarines are mutated to accept both rocket and nuclear fuel, which is undesirable for maraxsis.
2. lignumis and smoker changes likewise directly conflict with one another; the end result is that lignumis wins over the fuel category, and stone-smoker accepts no fuel at all

Having ItemPrototype::fuel_categories instead of a single fuel_category would make compatibility trivial in both cases: maraxsis, planet-muluna, and smoker could just add a new fuel category to the existing base game items instead of replacing it and having to do the energy_source fixup dance. lignumis could just replace chemical with wood on wood's fuel category list, without changing the also-listed smoking-chemical category.

In addition to the obvious incompatibilities above, it turns out that writing the code that patches a new fuel category onto existing entities is also error-prone, as I found multiple subtle issues:

• multiple mods only look at energy_source field of prototypes, failing to notice that other fields with the same semantics exist (BurnerGeneratorPrototype::burner, FusionReactorPrototype::burner, GeneratorEquipmentPrototype::burner, RoboportEquipmentPrototype::burner), leaving many unpatched entities that eg. no longer accept solid fuel
• BurnerEnergySource::fuel_categories is actually an optional field that defaults to {"chemical"}; however, most mods fail to take notice of that fact and will skip over any burners that happens to exercise that default
• planet-muluna had a funny case where the final versions of some machines (specifically muluna-vacuum-heating-tower) are only created in data-final-fixes, with partial intermediate versions being smuggled between data stages in data.raw["heat-assembling-machine"], which is not a real game prototype, and got skipped over by Age-of-Production's replacement code that only looked at a fixed list of prototype types that are known to have energy_source fields

In summary, I believe that having multiple fuel_categories on an ItemPrototype will let mods completely avoid several classes of compatibility problems, some of which are currently impossible to avoid without inter-mod cooperation.

[FluidNatalie]

As already stated by wanda-phi, this effects Maraxsis compatibility (as well as for Kryzeth's Maraxsis Classic) however even if this didn't cause issues I still think this is a very important change similar to crafting categories.

+1

[boskid]

1/ Item description for fuels has 2 lines that are based on fuel category: type of fuel ("Burnable fuel" / "Nutrients" / "Food") and fuel value ("Fuel value:" / "Yummy value:" / "Energy value:").
1a/ What should happen to the fuel type line? Should there be one line for each fuel category?
1b/ What should happen to fuel value line? Would it be enough to use FuelCategory::fuel_value_type from first fuel category only?

2/ If this was introduced, it would be a breaking change. Since we are still in 2.1 experimental stage that should be acceptable but there may be some backlash from players unable to play. How fast could modders adapt if this change was applied? This change would consist or rename of ItemPrototype::fuel_category into ItemPrototype::fuel_categories and rename of LuaItemPrototype::fuel_category into LuaItemPrototype::fuel_categories.

[Samario]

Regarding 2) I'm throwing my $0.02 in to note that all of the mods listed in this confluence of fuel categories (apart from Smoker, but its author is explicitly active) all rely on PlanetsLib already, and PlanetsLib can have some fallback code in it to smooth over the transition like how it does with other breaking changes in 2.1 so it shouldn't be toooo big of a deal
The item description thing is something I don't have as much of an explicit opinion on, but it makes sense for the fuel type line to list "Burnable fuel, Nutrients, Food" and fuel value line to list "Fuel / Yummy value:" to me, since I can't see them being added to THAT many things at once

[front]

1/ Item description for fuels has 2 lines that are based on fuel category: type of fuel ("Burnable fuel" / "Nutrients" / "Food") and fuel value ("Fuel value:" / "Yummy value:" / "Energy value:").
1a/ What should happen to the fuel type line? Should there be one line for each fuel category?
1b/ What should happen to fuel value line? Would it be enough to use FuelCategory::fuel_value_type from first fuel category only?

Communicating it is going to be the issue with that, and I have no good answer. :/
Maybe alias a fuel category? So in my smoker's case I use my own fuel category in my own machine so it can't take anything else, but it is also an alias for "chemical" so anything that wants chemical can still use it?

2/ If this was introduced, it would be a breaking change. Since we are still in 2.1 experimental stage that should be acceptable but there may be some backlash from players unable to play. How fast could modders adapt if this change was applied? This change would consist or rename of ItemPrototype::fuel_category into ItemPrototype::fuel_categories and rename of LuaItemPrototype::fuel_category into LuaItemPrototype::fuel_categories.

We are prepared to add code to planetslib as a temporary fix.

[cackling.fiend]

Better now than after the first stable release.

I didn't realize Lignumis is involved in this topic until I read the thread. Here is my +1.

[MeteorSwarm]

1/ Item description for fuels has 2 lines that are based on fuel category: type of fuel ("Burnable fuel" / "Nutrients" / "Food") and fuel value ("Fuel value:" / "Yummy value:" / "Energy value:").
1a/ What should happen to the fuel type line? Should there be one line for each fuel category?
1b/ What should happen to fuel value line? Would it be enough to use FuelCategory::fuel_value_type from first fuel category only?

2/ If this was introduced, it would be a breaking change. Since we are still in 2.1 experimental stage that should be acceptable but there may be some backlash from players unable to play. How fast could modders adapt if this change was applied? This change would consist or rename of ItemPrototype::fuel_category into ItemPrototype::fuel_categories and rename of LuaItemPrototype::fuel_category into LuaItemPrototype::fuel_categories.

I've already responded to a previous breaking change made by you(plural) in Factorio 2.1.13 with a PlanetsLib update that updated outdated planet fields in ambient-sounds, automatically replacing the old field with corrected fields in data-final-fixes if they exist. This change would be much more disruptive, but at least for planet mods, I could cover up a lot of the possible damage that this update would cause.

[MeteorSwarm]

I've prepared a branch of PlanetsLib that will fix other mods loaded alongside PlanetsLib to make the transition less disruptive for players. https://github.com/danielmartin0/Planet ... categories

[protocol_1903]

1/ Item description for fuels has 2 lines that are based on fuel category: type of fuel ("Burnable fuel" / "Nutrients" / "Food") and fuel value ("Fuel value:" / "Yummy value:" / "Energy value:").
1a/ What should happen to the fuel type line? Should there be one line for each fuel category?
1b/ What should happen to fuel value line? Would it be enough to use FuelCategory::fuel_value_type from first fuel category only?

For both questions, I feel that using the first category for localization is appropriate. In any case that I can think of, fuel_categories would only be used for thematically different but analagous fuels (i.e. chemical fuel vs biomass fuel vs carbonic fuel) where the type of fuel may differ but the energy value naming is the same throughout. In which case, the decision for which fuel type to display is up to the mod author(s) (if so, it should be noted in the docs which one is used). I feel that putting multiple category titles on the item would be more confusing than only having one listed.

2/ If this was introduced, it would be a breaking change. Since we are still in 2.1 experimental stage that should be acceptable but there may be some backlash from players unable to play. How fast could modders adapt if this change was applied? This change would consist or rename of ItemPrototype::fuel_category into ItemPrototype::fuel_categories and rename of LuaItemPrototype::fuel_category into LuaItemPrototype::fuel_categories.

As a non-planet modder and non-planetlib user, this would be a very quick fix for modders. Especially so if (like in 2.0) this was noted as a breaking change before being released so awareness could spread beyond those currently in this discussion. As for player backlash, I feel that it would be relatively minor (in fact it would probably help raise awareness for those out of the loop). We're early enough into the 2.1 dev cycle that mods aren't likely to be "done and left" yet, so I doubt much would come from this breaking change.

[boskid]

Implemented for 2.1.20.

[Bilka]

I've prepared a branch of PlanetsLib that will fix other mods loaded alongside PlanetsLib to make the transition less disruptive for players. https://github.com/danielmartin0/Planet ... categories

The patch will also have to remove fuel_category from the item prototype. (Also, good luck in N months whenever you remove the patch and break a bunch of mods that depended on it.)