Documentation Improvement Requests

[moon69]

LuaSurface.create_entity documentation doesn't have advice for "stream" type entities.

It appears to be the same requirements as type "beam", but it would be nice to be sure.

-> Mostly similar, yep, thanks. Added for 1.1.70.

[moon69]

RE: FluidStream.particle_buffer_size prototype documentation... the value must be greater than zero! So...
0 < particle_buffer_size < 256

Also: It appears this setting determines the number of spawned children of the stream... could this be documented please?

-> Thank you Honktown for adding this to the wiki.

[moon69]

Prototype/Animation.layers documentation was copy/pasta from Types/Animation.layers and doesn't really make sense here.

layers
Type: table of Animation
If this property is present, all Animation definitions have to be placed as entries in the array, and they will all be loaded from there. Each item (Animation definition) in the array may also have the layers property.
If this property is present, all other properties are ignored and the mandatory properties do not have to be defined.

Layers may not be an empty table.

Since the only mandatory properties for Prototype/Animation.layers are 'name' & 'type', this gives...

Code: Select all

data:extend({
  {
    layers =
    {
      {
        name = "test-animation",
        type = "animation",
        animation_speed = 0.5,
        ...

The mandatory properties 'name' & 'type' I assume must be at the same level as 'layers' and are not ignored?
I think it should be like this?

Code: Select all

data:extend({
  {
    name = "test-animation",
    type = "animation",
    layers =
    {
      {
        animation_speed = 0.5,
        ...

-> Thank you for pointing this out, I fixed the description. It acts like you assume. Prototype/Sprite had the same issue, also now fixed.

[Honktown]

RE: FluidStream.particle_buffer_size prototype documentation... the value must be greater than zero! So...
0 < particle_buffer_size < 256

Also: It appears this setting determines the number of spawned children of the stream... could this be documented please?

Spawned children particles, to be clear? If you sign up for the wiki, you can make the edits yourself btw.

-> Thank you Honktown for adding this to the wiki.

[Honktown]

LuaForce.get_train_stops
The name parameter is the name of the stations, not the prototype. Please note.

-> Noted, thanks. I also added explanations for the default behavior of all those parameters. Added for 1.1.70.

[Pi-C]

I've been wondering why my selection tool would find car prototypes although selection_mode was set to {"entity-with-owner"}. Turns out there is a bug in the prototype descriptions.

According to Prototype/Vehicle, vehicle prototypes are Prototype/EntityWithOwner:
Prototype definitions » PrototypeBase » Prototype/Entity » Prototype/EntityWithHealth » Prototype/EntityWithOwner » Prototype/Vehicle

However, Prototype/EntityWithOwner is missing from the descriptions of Prototype/Car and Prototype/SpiderVehicle.


Also, according to Prototype/RollingStock, rolling stock is Prototype/EntityWithOwner as well. But Prototype/EntityWithOwner is missing from the description of Prototype/ArtilleryWagon, Prototype/CargoWagon, and Prototype/FluidWagon (the description is correct for Prototype/Locomotive).

-> This was a caching issue, entity with owner of course also applies to the derived classes. The caching should be fixed with the update of the wiki software (we cleared the cache at some point here) but just to be safe I manually cleared the cache of the mentioned pages again.

[Honktown]

I've been wondering why my selection tool would find car prototypes although selection_mode was set to {"entity-with-owner"}. Turns out there is a bug in the prototype descriptions.

According to Prototype/Vehicle, vehicle prototypes are Prototype/EntityWithOwner:
Prototype definitions » PrototypeBase » Prototype/Entity » Prototype/EntityWithHealth » Prototype/EntityWithOwner » Prototype/Vehicle

However, Prototype/EntityWithOwner is missing from the descriptions of Prototype/Car and Prototype/SpiderVehicle.


Also, according to Prototype/RollingStock, rolling stock is Prototype/EntityWithOwner as well. But Prototype/EntityWithOwner is missing from the description of Prototype/ArtilleryWagon, Prototype/CargoWagon, and Prototype/FluidWagon (the description is correct for Prototype/Locomotive).

Unless it was changed within the last day, they're all there for me, the next "Inherited from" below "Prototype/Vehicle". It's also at the top after "Prototype/EntityWithHealth". Where are you looking?

-> This was a caching issue, entity with owner of course also applies to the derived classes. The caching should be fixed with the update of the wiki software (we cleared the cache at some point here) but just to be safe I manually cleared the cache of the mentioned pages again.

Most likely it was showing up differently because the cache is refreshed more aggressively for logged in users.

[Pi-C]

Unless it was changed within the last day, they're all there for me, the next "Inherited from" below "Prototype/Vehicle". It's also at the top after "Prototype/EntityWithHealth". Where are you looking?

I meant at the top. This seems to have been changed for "car" and "spider-vehicle" in the meantime, but "Prototype/EntityWithOwner" was still missing for rolling stock when I made these screenshots about half an hour ago:

rolling_stock.png (434.43 KiB) Viewed 5171 times

-> This was a caching issue, entity with owner of course also applies to the derived classes. The caching should be fixed with the update of the wiki software (we cleared the cache at some point here) but just to be safe I manually cleared the cache of the mentioned pages again.

Most likely it was showing up differently because the cache is refreshed more aggressively for logged in users.

[Honktown]

Huh, ok. They're there for me, for all the screenshots without. Sorry if I interrupted someone in the middle of it.

-> This was a caching issue, entity with owner of course also applies to the derived classes. The caching should be fixed with the update of the wiki software (we cleared the cache at some point here) but just to be safe I manually cleared the cache of the mentioned pages again.

Most likely it was showing up differently because the cache is refreshed more aggressively for logged in users.

[curiosity]

Prototype/SelectionTool#selection_mode
What is the difference between "buildable-type" and "items-to-place"? What are "the normal rules"? How do flags combine?

The runtime docs are even less descriptive: SelectionModeFlags. And "avoid-rolling-stock" is not listed. Does this mean the flag doesn't exist in runtime or is it missing?

-> Thanks, they were indeed quite outdated. I added missing ones and wrote descriptions for each one, for both the wiki and the runtime docs. Wiki is live now, runtime docs will be with 1.1.70.

[Muppet9010]

LuaItemPrototype.get_ammo_type() says its only argument is a `string?`, but it doesn't say what its behaviour is if you don't provide it. I assume `default` as its first in the allowed values list?

https://lua-api.factorio.com/latest/Lua ... _ammo_type

-> "default" is indeed the default, which is noted for 1.1.70. Thanks.

[Muppet9010]

LuaSurface.get_tile() says it accepts either x and y of int values or a TilePosition object. However it seems to work fine if you pass it x and y double values or a MapPosition object.
This difference appears more when using Sumneko for typing or that it implies to the modder they need to floor their values before passing them in.

https://lua-api.factorio.com/latest/Lua ... e.get_tile

-> This is a bit of a weird situation. It does accept doubles, but converts them to ints anyways. I think in this case it's not really worth it to document it as doubles, since you want ints, it just happens to deal with doubles as well (partly because in Lua 5.2, there are no real ints, everything is a double). I added a note that doubles are rounded down. Maybe Sumneko being angry at you is a good thing, makes sure you're aware that tiles are integers

[Honktown]

It is a thing that get_tile takes a position, and is not labelled so. Good find.
lol it is a half-nevermind:

Code: Select all

Note
The input position params can also be a single tile position.

The documentation type isn't multiple, like with script.on_event, but it's literally noted. Lacking the type in the documentation is probably because the documentation doesn't handle multiple requirements *across* arguments (as I understand). If the first argument is a position, the next argument isn't allowed at all. "Less than nil", because the C++ side counts each argument and some functions will error with improper counts and combinations.

The teleport function is, similarly, not described completely

-> Yup you're spot-on, some (particularly older) methods have multiple call signatures, and the doc system doesn't support this at the moment. It's on the todo list to do that, but no timeline on it for now.

[Hornwitser]

trains_count is marked as read only but its description mentions writing to it (emphasised by me).

https://lua-api.factorio.com/latest/Lua ... ains_count
[quote]trains_count :: uint [Read]
Amount of trains related to this particular train stop. Includes train stopped at this train stop (until it finds a path to next target) and trains having this train stop as goal or waypoint. Writing nil will disable the limit (will set a maximum possible value).[/quote]

-> Fixed: this comment was moved from trains_count to trains_limit.

[InappropriatePenguin]

The "type" field of a CapsuleAction object is "artillery-remote" for artillery targeting remotes. This is not included as one of the possible options for that field in the docs.

To verify, hold an artillery remote in your cursor and type:
[code]/c game.print(game.player.cursor_stack.prototype.capsule_action.type)[/code]

-> Thanks, that concept was very underdocumented in general, which I rectified for 1.1.70.

[Muppet9010]

The recently added range_modifier, cooldown_modifier, consumption_modifier fields to AmmoType concept don't look to have been included in the documentation.

Added in to 1.1.64 as part of this Modding Interface request: viewtopic.php?f=65&t=103012

-> This was added sometime in the past.

[Muppet9010]

The LuaControl.mining_state lists the `position` field as optional, however, if you don't provide it for your player an on screen warning text appears stating that its needed, or the script causes an error.
https://lua-api.factorio.com/latest/Lua ... ning_state

The warning text is:
[quote]Cannot execute command. Error: 'position': table expected, got nil[/quote]

For testing with the player I used the below on a new map. This does the targeting and mining every tick so it completes. If the position isn't provided in the mining command then the warning text is shown / a script error occurs for the missing position.

Code: Select all

/sc
local player = game.player
local furnace = player.surface.create_entity({name="stone-furnace", position={x=game.player.position.x+3, y=game.player.position.y+3}, force=player.force})
script.on_event(defines.events.on_tick, function() 
  if furnace.valid then
    player.selected = furnace
    player.mining_state = { mining = true, position = furnace.position}
  end
end)

However when using a character without a player I did find that once I had set a position in to the mining state once I didn't have to provide it for subsequent mining state commands. I guess this is somehow related to player inputs being reset every tick, but non player entities input not. As a similar thing happens with walking_state and players needing it set every tick, whereas lone entities will just continue walking indefinitely.

-> That's a weird one, not sure why the docs said that, it's not what the code does at all. It's simply reading the position if mining is true, otherwise it doesn't. The docs for these writeable properties is are kinda weird sometimes. Anyways, improved for 1.1.79.

[Muppet9010]

LuaSurface.create_entity for projectile has a few missing details:
https://lua-api.factorio.com/latest/Lua ... ate_entity

[list=1]
[*]max_range is optional
[*]the type "artillery-projectile" appears to have the same options/requirements as "projectile". With at least "speed" being required.
[/list]

-> Thanks, fixed for 1.1.70.

[BiterUnion]

I hope this is the right sub-forum, let me know if I should move this topic to Bug Reports.

I think I have found some inconsistencies/missing information in the machine-readable API documentation, specifically the documentation for LuaGuiElement. All of the following list items relate to the json data for LuaGuiElement:
[list]
[*]Inconsistent capitalization/dashing for subclasses:
[list]
[*]Attribute "state" has "RadioButton" in "sublasses", but the type is written as "radiobutton".
[*]Attribute "state" has "CheckBox" in "sublasses", but the type is written as "checkbox".
[/list]
[*]Missing subclasses:
[list]
[*]Attribute "mouse_button_filter" is missing subclasses "button" and "sprite-button".
[*]Attribute "clicked_sprite" is missing subclass "sprite-button".
[*]Attribute "entity" is missing subclasses "entity-preview", "camera", "minimap".
[*]Attribute "force" is missing subclass "minimap".
[*]Attribute "items" is missing subclasses "drop-down", "list-box".
[*]Attribute "number" is missing subclass "sprite-button".
[*]Attribute "position" is missing subclass "minimap".
[*]Attribute "resize_to_sprite" is missing subclass "sprite".
[*]Attribute "selected_index" is missing subclasses "drop-down", "list-box".
[*]Attribute "show_percent_for_small_numbers" is missing subclass "sprite-button".
[*]Attribute "sprite" is missing subclasses "sprite-button", "sprite".
[*]Attribute "surface_index" is missing subclasses "camera", "minimap".
[*]Attribute "tabs" is missing subclass "tabbed-pane".
[*]Attribute "zoom" is missing subclasses "camera", "minimap".
[*]Method "add_item" is missing subclasses "drop-down", "list-box".
[*]Method "clear_items" is missing subclasses "drop-down", "list-box".
[*]Method "get_item" is missing subclasses "drop-down", "list-box".
[*]Method "remove_item" is missing subclasses "drop-down", "list-box".
[*]Method "set_item" is missing subclasses "drop-down", "list-box".
[/list]
[*]Description of attribute "resize_to_sprite" says "Whether the image widget should resize ...", but I think it should be "Whether the sprite widget should resize ...", as the subclass is called "sprite" and not "image".
[/list]

-> This is the right sub-forum, appreciate the detailed list. The whole subclasses system is kind of crappy and not very useful for machine-readability, so the plan is to replace it with something better in the future. Still, I fixed these points for 1.1.70.

[Honktown]

https://lua-api.factorio.com/1.1.67/Lua ... flashlight

This doesn't work on a player, only an entity, and presumably only a character? It'd be worth documenting imo, but I'm not sure if it was supposed to work on players and it not working now is a bug. (Edit: it's listed under LuaPlayer, which is why I got the impression it should work for a player)

Edit: I reported this as a bug, since it's a bit strange: viewtopic.php?f=7&t=103187

-> This was indeed a bug, thanks for reporting it.