Proper documentation for "data.lua"

[thelordodin]

We have good docs for API here:
https://lua-api.factorio.com/0.16.51/

But we don't have any docs for what we feed into "data.extend" from "data.lua" or "data-updates" etc.

As a workaroud there is some info:
- Scattered in quite many old forum topics mixed with some many-paged discussuions
- Some info in wiki here - https://wiki.factorio.com/User:Adil/Modding_tutorial
- Some info on Reddit
- And you can also view base mod as a reference

You ofcourse can live as it is, we all can live with with that.

But:
- For new modders it's quite hard to start.
- This results in asking questions over and over.
- And even though some of expert modders come to know some feature existed just now
- Some of this isn't obvious at all. Example:
viewtopic.php?f=25&t=56680&p=335270&hil ... nt#p335270
- Another funny example: viewtopic.php?f=28&t=61214
- All this results in that modders is unsure if something is possible and if it is - how to do that?

- I also think that doing this docs may actually be useful not just for modders and for devs too. I don't think you all remember all you have written for all this years to this loading stage.
This might be another pitfall of underestimation like "it's just GUI" - "we just need to feed SOME data"... It's not "SOME" already...

There is no single reliable source for this knowledge about difining prototypes.
I think that would be great if all this is included here https://lua-api.factorio.com/

[Bilka]

https://wiki.factorio.com/Prototype_definitions

[Optera]

The wiki is great, but a fully auto generated documentation for all prototype properties and flags as well as some clue as to what they really do would go a long way.

It should also include the helper functions that where added.
One recent example that cost me half a day of trial and error to get a hold of is "circuit_connector_definitions".

[Bilka]

The wiki is great, but a fully auto generated documentation for all prototype properties and flags as well as some clue as to what they really do would go a long way.

Of course. Autogenerated documentation is still planned.

But right now, the wiki lists almost all prototypes. I can also guarantee that every prototype page that exists is complete. If you need more information on a certain property, please simply message me (Pm here or discord or whatever) and I will add that information. It's simply not there yet because it can take a very long time to find that information sometimes. But I am very much willing to add it if there is specific demand - in the future it will help fill up the autogenerated documentation.

Sidenote: I am pretty curious how OP found https://wiki.factorio.com/User:Adil/Modding_tutorial

[thelordodin]

Thanks VERY much!
It's great! Pity there is no link to it from Factorio API. Can you add it please?

There are some issues found by the first glance:
https://wiki.factorio.com/Prototype/Sprite - is empty
https://wiki.factorio.com/Types/SpriteNWaySheet - is empty

Many interesting fields has no description. Example:
https://wiki.factorio.com/Types/Sprite
- what is "load_in_minimal_mode"? What is "minimal_mod"?
- whats the difference between "slice" and "slice_x"?
- "shift" - needs a notice that it's not pixels here...

Many links to
https://wiki.factorio.com/Types/****
but
https://wiki.factorio.com/Types - is missing

Also I've tried to fugure out what the "Sprite" is. I'm developing a mod related to circuits and combinators, so I first looked at "Constant Combinator"

So there is at least this ones:
https://wiki.factorio.com/Types/Sprite
https://wiki.factorio.com/Types/Sprite4Way
https://wiki.factorio.com/Types/RotatedSprite
https://wiki.factorio.com/Types/SpriteNWaySheet

There is also layers...

I can't figure out how this sprites all works togather and how should I make my "Combonator" for "Combinissimo" (viewtopic.php?f=33&t=64210)...

[Bilka]

There are some issues found by the first glance:
https://wiki.factorio.com/Prototype/Sprite - is empty
https://wiki.factorio.com/Types/SpriteNWaySheet - is empty

They are documented now.

Many interesting fields has no description. Example:
https://wiki.factorio.com/Types/Sprite
- what is "load_in_minimal_mode"? What is "minimal_mod"?
- whats the difference between "slice" and "slice_x"?

These particular field are not at all interesting for modders but I still gave them descriptions.

but
https://wiki.factorio.com/Types - is missing

What would be on that page? The different types have literally nothing in common.

I can't figure out how this sprites all works togather and how should I make my "Combonator" for "Combinissimo"

I think you are missing a fundamental thing: How graphics are rendered all depends on the entity you are using. You cannot pick one "graphics type". Instead you pick an entity and then deal with the way it loads its graphics.

[thelordodin]

I think you are missing a fundamental thing: How graphics are rendered all depends on the entity you are using. You cannot pick one "graphics type". Instead you pick an entity and then deal with the way it loads its graphics.

I do understand this. But this is implementation approach: you have entity types and the way it's rendered. And all this is good because you just implement this way entities. But when a modder wants to make a new entity - it's always someway composed of other entites.


But when a modder wants to make a new entity - it's always someway composed of other entites.

Few examples:
I want to do a "Combonator" with several 4 input/output connectors.

If I would be inside factorio devs team I would make a new cpp class a new behavior and finally a new entity type and it would have it's personal way of rendering.
But I'm a modder...

So what I do:
I'm going to use
- "Programmable speaker" - because its the only entity in game which allows storing string data (inside "Alert" field)
- 4 "Pole" entities - as input/output connectors
- Several combinators (constant, decider, arithmetic) entities - to implement the logic (and I'll make them invisible)
- Another "pole" and a "solar-panel" to power editor's interiors

And... I wonder if I need some other entities to render the graphics nicely.
So I need to find some entities which are the best way matching my needs for rendering.
For example if I need glowing I would choose "Centrifuge".

So for modders it would be useful to which entities' sprites are capable of what.
When I wrote this post it turned out it's too big for this topic, so here it is now: viewtopic.php?f=28&t=64340&p=393523#p393523

[thelordodin]

but
https://wiki.factorio.com/Types - is missing

What would be on that page? The different types have literally nothing in common.

Well I just wanted all sprite related types on some page to figure out what types of sprites are there and maybe finding out which entities do I need to use to implement wanted rendering behavior.

[Bilka]

The prototype documentation is now auto-generated from source code comments (like the runtime docs) and can be found here: https://lua-api.factorio.com/latest/ind ... otype.html. https://lua-api.factorio.com/latest/types.html provides an overview of all the types.