LuaSurface.request_path documentation

[Honktown]

(Note from Therenas: Split this discussion out to its own thread so the doc improvements one isn't cluttered up with it)

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.

Erm, it doesn't take an entity prototype or anything at all, only a bounding box and collision mask. The bounding box could even be dimensions that no prototype uses. I suppose the use of "unit" in the description might confuse someone. If you were to "clarify" it, would you have any suggestions?

[Pi-C]

LuaSurface.request_path

Erm, it doesn't take an entity prototype or anything at all, only a bounding box and collision mask. The bounding box could even be dimensions that no prototype uses.

Oh, you're right.

I suppose the use of "unit" in the description might confuse someone.

Especially if that someone is working on a vehicle mod and has to deal with another mod replacing cars with units for pathfinding. That's why my first reaction was: "Wait, that's not limited to units, we've used that for cars!"

If you were to "clarify" it, would you have any suggestions?

Prototype/Unit is a subset of Prototype/EntityWithHealth, so replacing "a unit" with "an entity" should be clear enough. "Entity" is such a general term that it covers even particles and projectiles.

[posila]

Prototype/Unit is a subset of Prototype/EntityWithHealth, so replacing "a unit" with "an entity" should be clear enough. "Entity" is such a general term that it covers even particles and projectiles.

I feel like such phrasing might create an impression that it is possible to order any entitiy to follow a path found by the pathfinder ... which is not true. Only units (and ) can follow (pathfinder) paths. What about changing "a unit" to "any unit"?

[Pi-C]

Prototype/Unit is a subset of Prototype/EntityWithHealth, so replacing "a unit" with "an entity" should be clear enough. "Entity" is such a general term that it covers even particles and projectiles.

I feel like such phrasing might create an impression that it is possible to order any entitiy to follow a path found by the pathfinder ... which is not true. Only units (and ) can follow (pathfinder) paths. What about changing "a unit" to "any unit"?

Then we'd still have the issue that "unit" is the prototype for biters/spitters. You could leave the sentence as it is if you'd add another one where you point out what prototypes this applies to: unit, car, spider-vehicle and character would be the most obvious. But perhaps somebody would make a mod where you place just one miner (thinking of big excavators) on an ore patch and let it path to another patch once the first has been depleted? The term "entity" would allow for that.

[posila]

Then we'd still have the issue that "unit" is the prototype for biters/spitters. You could leave the sentence as it is if you'd add another one where you point out what prototypes this applies to: unit, car, spider-vehicle and character would be the most obvious. But perhaps somebody would make a mod where you place just one miner (thinking of big excavators) on an ore patch and let it path to another patch once the first has been depleted? The term "entity" would allow for that.

But car, spider-vehicle nor character cannot be ordered to move along the path, only units can. The sentence is there just to make it clear, the pathfinding request is not tied to any unit actually moving. And unit is the only possible entity type that could be ordered to follow the path on its own.

[Pi-C]

But car, spider-vehicle nor character cannot be ordered to move along the path, only units can. The sentence is there just to make it clear, the pathfinding request is not tied to any unit actually moving. And unit is the only possible entity type that could be ordered to follow the path on its own.

Sorry, you're right! Looked at the mod code again: We've abused request_path to get the path and moved our cars to the next position on it per script … Yes, it's been a long time since I've touched that mod (it hasn't even been updated to 1.1 yet), so I'm afraid I mixed things up.

[eradicator]

The sentence is there just to make it clear, the pathfinding request is not tied to any unit actually moving. And unit is the only possible entity type that could be ordered to follow the path on its own.

Wait wait wait.......

As far as I understand LuaSurface.request_path and on_script_path_request_finished are exclusively used to calculate paths for non-units. Moving units is done via LuaEntity.set_command or LuaUnitGroup.set_command, neither of which takes <path :: array[PathfinderWaypoint]> as an input paramter. Units can calculate the path themselfs. So the main usecase for LuaSurface.request_path to me seems to be giving scripts the ability to move $something *like* it was a unit, but without it *being* a unit.

Code: Select all

Starts a path find request without actually ordering a unit to move.

→

Code: Select all

Finds a path using the unit pathfinding algorithm.

[Therenas]

Appreciate all the feedback, I'll change the method description to lay out these nuances.