Document FIND_DROPPED_RESOURCES

[shedletsky]

The docs are very unhelpful.

What object type does this return?

[Gankdalf]

@shedletsky http://docs.screeps.com/api/#Resource

[shedletsky]

@gankdalf it's possible I've just been staring at it too long, but I can't tell why this is an error when there are no dropped resources in the room.

The next line of code prints out [] if you remove the filter.

[Gankdalf]

@shedletsky .find() always returns an array of the object type you are searching for, regardless of how many are returned.

EDIT and iirc the filter needs to be a function not a condition

[Gankdalf]

let res = creep.room.find(FIND_DROPPED_RESOURCES, { filter: (o) => o.resourceType === RESOURCE_POWER });

would likely be what you are looking for

[shedletsky]

@gankdalf you know, looking at it again, I'm pretty sure it needs to be

But damn some more examples in the docs would have made this a lot more fun.

[artch]

let res = creep.room.find(FIND_DROPPED_RESOURCES, { filter: (o) => o.resourceType === RESOURCE_POWER });

let res = creep.room.find(FIND_DROPPED_RESOURCES, { filter: { resourceType: RESOURCE_POWER }});

These notations are fully identical. The documentation you're looking for is probably lodash.filter docs, not FIND_DROPPED_RESOURCES docs.

[shedletsky]

@artch

Since the invocation required is so idiomatic to javascript/lodash, I'm sure it would help a bunch of players to have a couple more examples of all the ways you can call .find in the docs. I've been playing for two years and I still have to look it up every time and I still have bugs where I use .find + filter incorrectly pretty much constantly.

[Gankdalf]

@shedletsky does clicking the link not show the examples I see when I click it?

EDIT - and you can edit the docs yourself through a pull request if you don't think they are sufficient.

[shedletsky]

@Gankdalf

Yes, that link goes to the lodash examples for filter, which I have to consult constantly when I'm coding screeps, partly because the 3 provided examples in the wiki don't cover every case.

Having a polymorphic .find() that returns a different type depending on a constant you pass in is very odd (if you program in other languages). It's worse because it does no validation on the input and doesn't give helpful errors when you invoke it incorrectly (it fails silently, which, if you program in other languages is also odd). The article in the wiki doesn't even link to the return types that it can spit out (for example, the Resource object in the case of FIND_DROPPED_RESOURCES). Boo urns.

On top of that, it is fairly opaque to me what, if any, caching .find does and the docs don't talk at all about that. Is it worth putting my own cache in front of it? I have no idea. What kind of .finds are cached or fast? Which ones are slow? I have to imagine that depending on the FIND_CONST you pass in, it is very different.

[Gankdalf]

@shedletsky What you might be looking for in that regard is the engine source:

That cache is clearly visible near the top of the .find() function
https://github.com/screeps/engine/blob/master/src/game/rooms.js#L543

[shedletsky]

@gankdalf

I don't understand how this cache works just by looking at it, do you? I don't even understand what "this" is in this context.

@artch Dissi posted a while ago asking about things that are hard when you are starting out playing Screeps. The .find() function is key to doing literally everything and this is the sum total of all the documentation about it:

Yes, I can figure it out for myself with enough time, but if I have to get too into the weeds it starts to feel more like work and less like I'm playing a game. Even just adding some hyperlinks to those FIND_* constants and the possible return types I'm sure would help a lot of people who are trying to get started.

[Gankdalf]

@shedletsky because it is a modification of the Room prototype, this refers to the room, so this.name is the name of the room. That cache is essentially caching queries by type and room. If you make a query from find() by the same FIND_* constant and roomName then it will have the results of that query cached.

Your custom filtering on top of that is not cached.

The FIND_* constants can be found in the constants section of the docs near the top, although I do agree that in general finding the desired constant is not always a trivial task, and can be infuriating when it doesn't exist.

As a note it is not actually that unusual a thing to have a function to return different types based on the passed constant. Javascript just doesn't support the normally accepted dynamic T notation of C# or other languages room.find<Tombstone>();, so they hacked together something extremely similar.

So as just a summary, the list of things you want to see changed are:

• links to applicable constants (not sure if this is possible)
• a mention of what exactly is cached by .find()
• a description of what is included in the return of each FIND_* type

I can try to put a pull request on the docs later, since they are open source.

[Gankdalf]

@shedletsky This is my first attempt at adding it to the docs. This is my local copy. I am not sure the formatting is consistent this way, but I have run out of time for goofing off on this.

EDIT - and it seems the wording on custom filters not being cached needs reworded ... the base query is cached, but the filtering is not cached.