Documentation Improvement Requests

[eradicator]

Maybe add a small note to the API doc that

Code: Select all

LuaForce.research_queue = {'automation','construction-robotics','automation'}

behaves the same as if a player did it. Aka:

Code: Select all

Note: Technologies that could not be normally researched by the force are silently ignored.
I.e. If their prerequisites are not met, or they have already been researched.

I found it a bit suprising, as usually the API allows mods to ignore normal limitations.

-> Thanks, added for the next release.

[eradicator]

Shortcut icons (normal + small + disabled) Are not normal "Sprite" types as they ignore the scale property to keep shortcut button style unified. (didn't test for other things like shift). As such the example is also misleading as it explicitly defines "scale = 1" for all icons.

-> Example updated to 1.1.34. It comes from the base game which sets the scale. I'm investigating why the scale is set when it doesn't seem to do anything.

=> If it is intentionally as I suspect and not a bug then I still think that showing scale in the example gives the wrong impression that it is somehow meaninful or nessecary. All my shortcuts are defined without scale and work as expected.

-> Scale removed from example, page updated to explain why it may not work as expected.

[Muppet9010]

LuaSurface.can_place_entity() requires inner_name when the the entity you are trying to test place is an "entity-ghost". The docs don't mention it, but you get a missing key error.
https://lua-api.factorio.com/latest/Lua ... ace_entity

Looks to be the same usage as the "entity-ghost" other attributes listed for the LuaSurface.create_entity().
https://lua-api.factorio.com/latest/Lua ... ate_entity

-> Thanks, fixed for the next release

[Pi-C]

Regarding LuaPlayer.create_local_flying_text:

time_to_live :: uint (optional)
speed :: double (optional): Movement per second

Units are missing here! Generally, ticks are used for time_to_live, but it wouldn't hurt if this was explicitly mentioned. However, "movement per second" is absolutely not enough: Does that refer to tiles per second, or is it a multiplier applied to the speed of vanilla flying text?

-> Thanks for the hint, I overhauled that whole method for the next release.

[Muppet9010]

Autoplace specifiation peak documentation doesn't list the dimension attributes specifically, instead as `d_XXX`. This makes any machine reading of the API spec break, as it can't see that `temperature_optimal` is a valid attribute.

Code: Select all

d_optimal :: double: d is the dimension name; this attribute may occur multiple times, once for each dimension, every time with a different prefix.
d_range :: double: d is the dimension name.
d_top_property_limit :: double: d is the dimension name.
d_max_range :: double: d is the dimension name.

I also can't see in the API spec where it lists the name of the dimensions to go with its `d_XXX` description.
I found "temperature" and "water" as dimensions from exploring data.

https://lua-api.factorio.com/latest/Con ... cationPeak

-> Thanks, all the parameters are properly noted for the next release. Do note that they aren't explained, since that information is not really available.

[Deadlock989]

LuaGameScript.get_filtered_item_prototypes links to "#ItemPrototypeFilters" on the Concepts page, but the anchor is incorrect, it should go to ItemPrototypeFilter (singular).

Edited to add, same seems to be true for most or all of the *PrototypeFilter links on that page.

-> Thanks for letting us know, but it seems that this is a caching issue on your side in this case, the current links are correct. Anyone experiencing this should try Ctrl-F5 on the lua-api page to clear their cache and see whether that fixes it.

[PFQNiet]

Tools have prototype properties to describe how the durability should appear in the tooltip, but the actual usage of this isn't documented.

From looking at core.cfg it would appear that the locale entry gets given:

__1__: remaining durability
__2__: total durability
__3__: durability as a percentage

However this would be nice to have confirmed in the documentation, as well as anything I may have missed here
-> Confirmed, documented, including an example.

[Muppet9010]

The link to Event Filters on the latest API home page is broken.

https://lua-api.factorio.com/latest/#Events

Capture.PNG (30.96 KiB) Viewed 6087 times

-> Like you noted below (comments now deleted to not clutter up the thread), this has been moved to concepts. That particular link was missed somehow though, so thanks. Fixed for the next release.

[Deadlock989]

Equipment.ability_icon
ActivateEquipmentCapsuleAction.equipment

How are these used and what are their limitations? The only thing that uses ability_icon in vanilla is the discharge defence equipment, and it corresponds with the icon used by the DD remote capsule, which points back to the equipment with the equipment property of its capsule_action. But in tests I can't get it to work properly with anything except equipment of type active-defense-equipment (the number on the quickbar remote stays red 0). Are these properties restricted to active-defense-equipment or am I missing some trick?

Edited to add: I'm not even sure that ability_icon does anything at all - I edited the vanila DD equipment to use some other icon and couldn't find any in-game changes at all.

-> You are correct, ability_icon was unused. I've removed it in version 1.1.36.

ActivateEquipmentCapsuleAction.equipment loads any equipment, but only ActiveDefenseEquipment can be activated (and only ActiveDefenseEquipment has cooldown and AvailableAbilityCount implemented). Now documented on the wiki.

[Pi-C]

LuaSurface.request_path

Starts a path find request without actually ordering a unit to move. Result is ultimately returned asynchronously via on_script_path_request_finished.

This looks like it is for units (biters/spitters) only, but we use that for "car" prototypes in the "Autodrive" mod and I suppose it will also work with "spider-vehicle" prototypes.

(Note: Split discussion of this into its own thread)

-> I explained the nuances of this method for the next release, thanks for everyone's input.

[Muppet9010]

The runtime-api.json doesn't include Custom Input Events.
I did a search for selected_prototype in the api doc and only usage was as part of the LuaCustomInputPrototype
https://lua-api.factorio.com/latest/eve ... t%20Events

-> I initially excluded this one on purpose because it doesn't have a typical name for an event and I didn't want to break the tools that people write. I then realized that keeping it is the better solution because tools can still filter it out manually if they want to. Soo added for the next release, thanks.

[curiosity]

https://wiki.factorio.com/Prototype/Boiler#mode - what is this supposed to mean? And the entire page seems underdocumented: what do all the graphical properties mean? Most can be guessed about, but then there is patch. Also it's not very clear whether a boiler is hardcoded to water->steam (the vanilla ones have filtered fluidboxes), I think that should be said explicitly.
-> The modes and the output filter are now explained and I added a lot of info to the graphical properties.

[PFQNiet]

Would it be at all possible to do something like runtime-api.json but for the data stage? Defining what prototype classes exist, what properties they can/must have, what types, etc.? I feel like this could be a massive help for data-stage modding, just as runtime-api.json has been a massive help for control-stage stuff.

-> Well, this is not very easy to do as the prototypes are all documented on the wiki, which doesn't follow any completely machine-readable format. So without massive effort, this is not possible. I do however agree that it would be really great to have this, so we'll see if there's a way to make this a thing in the future. No timeline on that obviously.

-> After a long while, this is now a thing! https://lua-api.factorio.com/latest/aux ... otype.html

[Impatient]

Today I noticed for the first time, that imo the ingame recipe for uranium processing is not 100% clear. It states what are the chances for U-238 and U-235 to be the result, but it does not state how many of them. It says, that the input is 10 uranium ore, but on the output side, there are only the chances but not the quantity (0.7% U-235, 99.3% U-238). From my experience I know that the result is just one piece of one of the two types of processed uranium. But if I was ignorant or new, there would be no way to tell from the ingame information alone, would there? I might even assume, that for an input of 10 uranium ore I should get 10 pieces of some type of processed uranium.

Well, strike that. The problem probably is, that I never read recipes. Clearly - and I knew that - recipes say how many results are to be expected by the multiplier in the title (eg 2x Copper cable). The confusing part was, that in the case of "Uranium processing" the title is not the name of the product itself, like in majority of the recipes. I think everyone who reads recipes in an aware way, is used to, that the title somewhat intermingles recipe name, output product name and quantity. If anything my post could be an impuls to think about to unmingle recipe name and result name and quantity in the ingame tooltip.

-> This is more of a game feature, not a documentation one, so if you want your opinions heard, please make a thread in the Ideas and Suggestions forum.

[eradicator]

(I don't have a usecase for this, it's just one of these situations where I'm giving the doc a puzzled "wtf does this do" look.)

Prototype/Animation.mipmap_count and Prototype/Sprite.mipmap_count are documented as "Only loaded if this is an icon (has flag "group=icon" or "group=gui")." but I don't see any prototype that uses Animation as an icon, and the doc says there's no inheritance between Animation and Sprite. So is this some sort of future-compatibility thing? Or a copy/paste error?

-> Explanation of "inheritance" here: viewtopic.php?p=549058#p549058
-> Uselessness of mipmap_count is now documented for the animation type and prototype.

[lovely_santa]

On the wiki page about the property tree: https://wiki.factorio.com/Property_tree inside the explanation of the dictionary (https://wiki.factorio.com/Property_tree#Dictionary), there is a reference to the 'string' datatype (the key).

When clicking the reference, it goes to https://wiki.factorio.com/Property_tree#String rather than to https://wiki.factorio.com/Data_types#string

Implemented in https://wiki.factorio.com/index.php?tit ... did=186472

[curiosity]

It feels weird and inconsistent that there is no setting prototype page, but only https://wiki.factorio.com/Tutorial:Mod_settings. IDK what action this should warrant, if any.

-> As previously stated in this thread

The data stage docs won't document settings stage things.

There may be some improvements needed so that the tutorial can reliably function as a quick reference similar to the usual prototype pages, but the settings stage in general will not be integrated into the data stage doc.

[Klonan]

The collision_mask argument for surface.request_path is a bit confusing, in my opinion:

Code: Select all

collision_mask :: CollisionMask or array[string]

The collision mask is not the collision mask of the prototype for expected results (they are opposite collision masks!), and "array[string]" is an unusual term. I found viewtopic.php?t=34548 which describes a previous issue someone took with it (that it should be dictionary string → boolean). In addition, an array of string is accepted.

Command example

Code: Select all

/c
local player = game.player
local surface = player.surface

local args = {
	bounding_box = player.character.prototype.collision_box,
	start = player.position,
	goal = {-48, -35},
	force = "player",
	pathfind_flags = {
		cache = false,
	}
}

local masks = {
	[{"water-tile", "object-layer"}] = false, --[[around water and walls]]
	[{}] = false, --[[straight line]]
	[player.character.prototype.collision_mask] = false, --[[straight line]]
	[{["water-tile"] = true, ["object-layer"] = true}] = false, --[[around water and walls]]
}
for mask, do_it in pairs(masks) do
	if do_it then
		args.collision_mask = mask
		surface.request_path(args)
	end
end


local function on_script_path_request_finished (event)
	log(serpent.block(event, {maxlevel = 1}))
end

script.on_event(defines.events.on_script_path_request_finished, on_script_path_request_finished)

^only turn one mask on at a time for the in-game debug to show the paths, I guess. It won't show all of them at once (bug...?).

I am not exactly sure what you are asking,
Collision masks work the same as with entity building and prototype of entities:
https://lua-api.factorio.com/latest/Con ... lisionMask

That is, if 2 things shared any mask, they collide with each other.


So the collision mask given to request path is used to do the pathfind, if you give the collision mask of an entity, the pathfinder will naturally collide with that entity

The map of string->bool is pretty standard lua construct, it makes looking up things from prototypes quick and easy,
For instance if you wanted to know if something collides with 'water-layer',
You just do `return entity.collision_mask["water-layer"] ~= nil`

The format of array of strings is also accepted, because that is the format the data stage accepts,
So you can have the same definition shared across data and control

[PFQNiet]

Why do I have to dig through the game files to find what fields exist on MapSettings?

(Perhaps more importantly, this prevents them from appearing in runtime-api.json, causing "undefined property" warnings when using them.)

-> I finally got around to trudging through this, the concept will be properly documented in a future release.

[curiosity]

on_console_chat event doesn't capture /shout. Does it also not capture any other command-like messages? This should be clarified and noted in the docs.

-> Thanks, noted for the next release.