I miss documentation in the API

[TelemakFactorio]

Hi there,

I miss documentation in the API. I give you some examples :

There is a LuaEntityPrototype. Cool. What is an entity prototype ? No idea.

I read you can bind a character to a player. Cool. The documentation doesn't explain what is a character, and what the binding will do.

The documentation says there is inheritance, but you can't use the motherclass functions, so what's the use of this inherit dense paragraph ? Unless there is something the API documentation does not say ? Who knows.

entity.last_user can only be used if the entity can have an owner. OK, so what happens when you call entity.last_user on an entity that can't have an owner ? Nil value ? Game crash ? Absolutely no idea.

Thanks for reading,

Telemak

[betrok]

API pages themselves are just a reference manual with (almost) all possible object properties, available for mods.
Try to check wiki for more or less consistent articles.

[TelemakFactorio]

That's true. I am agressive and need english lessons.

I will ask my questions in the mod help if I can't find my answers in the wiki.

[eradicator]

entity.last_user can only be used if the entity can have an owner. OK, so what happens when you call entity.last_user on an entity that can't have an owner ? Nil value ? Game crash ? Absolutely no idea.

The usual behavior when you try to read an attribute from something that doesn't have that attribute is that you get an error about trying to read an attribute that doesn't exist and are thrown back to the main menu.

[darkfrei]

entity.last_user can only be used if the entity can have an owner. OK, so what happens when you call entity.last_user on an entity that can't have an owner ? Nil value ? Game crash ? Absolutely no idea.

The usual behavior when you try to read an attribute from something that doesn't have that attribute is that you get an error about trying to read an attribute that doesn't exist and are thrown back to the main menu.

Why not just nil? Why the error don't say which one parameter not exist?

[eradicator]

Why not just nil? Why the error don't say which one parameter not exist?

Because nil would be far worse to debug i assume. And the error does say pretty exactly what you did wrong.

[TelemakFactorio]

I have progressed today.
I have figured out that the character is the onscreen character with his abilities/weapons/equipment/... attached to the player.
The prototype is about something that is defined and not instanciated.
Thanks to inheritance you can access the "parent" properties or functions. Ex : Entity inherits from Position, you can code myEntity.Position["x"]

entity.last_user does an error ? That's not good for me I have to find a workaround in my code.

Edit : just added a test and a logfile. Happily in my event I can test if entity.lastuser is equal to nil. I have doubts it is general case.

[darkfrei]

Why not just nil? Why the error don't say which one parameter not exist?

Because nil would be far worse to debug i assume. And the error does say pretty exactly what you did wrong.

For example this console command:

Code: Select all

/c
  local props = {'alt_selection_border_color', 'alt_selection_cursor_box_type', 'alt_selection_mode_flags', 'always_include_tiles', 'attack_parameters', 'attack_range', 'attack_result', 'build_distance_bonus', 'burnt_result', 'can_be_mod_opened', 'capsule_action', 'category', 'curved_rail', 'default_label_color', 'default_request_amount', 'draw_label_for_cursor_render', 'durability', 'durability_description_key', 'entity_filter_slots', 'equipment_grid', 'extend_inventory_by_default', 'filter_mode', 'flags', 'fuel_acceleration_multiplier', 'fuel_category', 'fuel_emissions_multiplier', 'fuel_top_speed_multiplier', 'fuel_value', 'group', 'insertion_priority_mode', 'inventory_size', 'inventory_size_bonus', 'isluaobject', 'item_drop_distance_bonus', 'item_filters', 'item_group_filters', 'item_pickup_distance_bonus', 'item_subgroup_filters', 'limitation_message_key', 'limitations', 'localised_description', 'localised_filter_message', 'localised_name', 'loot_pickup_distance_bonus', 'magazine_size', 'module_effects', 'name', 'order', 'place_as_equipment_result', 'place_as_tile_result', 'place_result', 'reach_distance_bonus', 'repair_result', 'resistances', 'resource_reach_distance_bonus', 'rocket_launch_products', 'selection_border_color', 'selection_cursor_box_type', 'selection_mode_flags', 'show_in_library', 'speed', 'stack_size', 'stackable', 'straight_rail', 'subgroup', 'tier', 'tile_filter_slots', 'type', 'valid'}
  local exp_table = {}
  for name, prototype in pairs (game.item_prototypes) do
    local new_elements = {}
    for i, prop in pairs (props) do
      new_elements[prop] = prototype[prop]
    end
    exp_table[name] = new_elements
  end
  game.write_file('control_items.lua', 'exp_table = {' .. serpent.block (exp_table)..'}')

As you see, list "props" has all parameters that we have in game.item_prototypes.help() and we're get only those data export, which exists and not nil. So, why we can't get exception for all parameters?

Now (0.16.37) I get this file:

control_items.lua

(237.45 KiB) Downloaded 69 times

[eradicator]

@Telemak:
Unless you're trying to code some sort of universally applicable code bits you don't usually need to care about other entities that might not have a certain attribute. I.e. if you were watching on_build and filter it for example for type='assembling-machine' or something...then the attributes would always be the same. This whole thing is only relevant if you have to treat objects that you don't know anything about. Which should not be the case if this is the first mod you're writing.

I didn't realize you were actually looking for answers to the things you complained about in the OP, i assumed it was some generic complaint...

Entity: Any "object" you can see in the game world. Assemblers, biters, trees, etc.
Prototype: The fixed definition of any "thing" in factorio. Prototypes are defined in the data.lua stage and can not be changed while the game is running ("during runtime"). Each "thing" is basically initially an instance of a prototype. The prototypes defines the default properties of a "thing". ("Thing" isn't just entities, it's everything, including items, tech and abstract things such as item groups.)
Player: A "thing" that stores all information relalted to a single human player. Including but not limited to which character(s) the player controls. Notable "exception": In the sandbox scenario players have no associated characters.
Character: An entity of prototype-type "player" (confusing naming gotcha). Looks like "that guy you play" in the base game. Is usually "associated" (=controlled by) to a Player.
Inheritance: Some prototype classes inherit some properties from higher class types. I.e. LuaEntity inherits some (or rather all? not sure) properties that LuaControl supplies. As you never get access to a "LuaControl" type object via the api you don't really have to worry about that. It's more of an internal technical thing about how the api is implemented, not about how it is used.

@darkfrei: I'm not a dev. And i don't think this is the right place to ask that question ;).

[TelemakFactorio]

Thank you !
Yes it is a complain and an oriented complain

Eventualy I asked, based on your answer, how to filter an event for this very specific purpose in the mod help appropriate section.
viewtopic.php?f=25&t=59847