Documentation for PathFinder.use is confusing

SystemParadox

I've been around for a while and I consider myself to be a pretty advanced screeps player. I regularly refer to the screeps-engine source code to help understand exactly how some of the builtin methods work. One thing in particular that I have looked at a lot is exactly how the pathfinding methods work, because there are several of them and they all seem to have subtle variations.

However, despite all this I was extremely surprised to find after some testing today that Room.findPath, RoomPosition.findPathTo, RoomPosition.findClosestByPath and Creep.moveTo still use the old pathfinder by default!

The documentation for PathFinder.use states:

isEnabled boolean Whether to activate the new pathfinder or deactivate. The default is true.

I now realise that this is referring to the the isEnabled argument itself. In other words, PathFinder.use() is equivalent to PathFinder.use(true). However, it is easy to mistake this (as I did) to mean that by default the system will use the new pathfinder, especially as PathFinder.use is marked as deprecated.

The rest of the documentation regularly refers to the old/new pathfinder, but nowhere is it stated which the system actually uses by default.

So, I have two requests:

Please update the documentation to clearly state which pathfinder is used by default.
Why is PathFinder.use marked as deprecated if the new pathfinder is not the default? What is the long term plan here? What is the recommended usage? I thought it was deprecated because the old pathfinder is deprecated. Is it deprecated because the old pathfinder is preferred for Room.findPath, etc? If so, why?

I'm curious to know what everyone else is doing. Are you doing PathFinder.use(true) or are you using the old pathfinder? Or like me did you think you were using the new one but discovered that you're still using the old one?

Thanks.

SystemParadox

I'm now even more confused as I've just seen a PTR changelog which states that it is the new pathfinder that is used by default (https://screeps.com/forum/topic/1108/ptr-changelog-2016-04-08).

This is not what I'm seeing.

room.findPath paths to the edge of the first room and stops.

Flyasd1

@systemparadox You are wrong all methods use new path finder for default. You can look into the method Room.findPath and you will see this condition

if(register._useNewPathFinder) {
      return _findPath2(this.name, fromPos, toPos, opts);
}

And you can look on the Game.js where register object are created line 114:

 var register = {
     _useNewPathFinder: true,
     _objects: {},

SystemParadox

I think I've found the cause of the confusion. In Room.findPath (https://github.com/screeps/engine/blob/master/src/game/rooms.js#L281), there is the following:

var ret = globals.PathFinder.search(fromPos, {range: Math.max(1,opts.range || 0), pos: toPos}, searchOpts);
for(let i=0; i<ret.path.length; i++) {
    let pos = ret.path[i];
    if(pos.roomName != id) {
        break;
    }
    //...
}

This break statement is why Room.findPath only returns paths up to the room exit (in this case id is equivalent to this.name).

The documentation for RoomPosition.findPathTo states:

If the target is in another room, then the corresponding exit will be used as a target

So this is expected for RoomPosition.findPathTo, but no such statement exists for Room.findPath, so the behaviour I am seeing is totally unexpected. It's even more confusing when you consider that the documentation for Room.findPath refers to options such as maxRooms.

So the game does use the new pathfinder by default, but the results from Room.findPath are totally confusing. It uses the new pathfinder to find a path all the way to the target but only returns the part of the path inside the current room and discards the rest.