Draft: Store prototype API

[W4rl0ck]

I would also prefer store .. it's short and I think it fits.

[MrFaul]

@davaned I know this seems like nitpicking but trust me I have seen markets shut down because of such little things like confusing naming conventions. (they switched logistic software)
Oh and cargo on a terminal makes perfect sense, just ask a port worker of your choice ^^

And again I'm not bitching about the term, I'm bitching about the lack of distinction.
I guess I'm just sensitized to filter out those problems early... ( That day mentioned above was a fuck up above 7 digits)

[Davaned]

@mrfaul

• Tower.store - has verb implication, valid word choice
• Tower.cargo - has incorrect implication, not getting transported
• Tower.contents - most accurate, extra characters

Would you describe something stored in your pantry as "cargo"? Between the contents of the pantry and the cargo of the pantry I know which makes sense. Store is a little clunky, but I would not bother changing to an incorrect definition.

[deft-code]

More bad options:

• hold. Same verb problem as store, same transit problem as cargo. less characters
• resources, almost as good as contents, but longer, resources is often used abstractly in common english.
• quanta, technically as correct as contents, horrifically confusing.
• bikeshed, terrible, but think of the story we could tell new players
• stuff, also a verb like store, but most often used as a noun, often used to end bikeshed arguments.

Seriously though, the consistent use will be a huge boon to those learning the API. The debate about which name is truly just bike shedding. There are bad options, many good enough options, and no objectively best options. More important than picking among good enough names is that the devs remain productive and this gets rolled out before the next crop of new players shows up.

If switching to contents speeds up the refactor, awesome. If leaving it as store means less work overall even better.

[wtfrank]

Renaming commonly-used variables 5 years into a project is often a terrible idea

[Orlet]

I'll miss Creep.carry, but .store is my preferred way of storeing things.

[Davaned]

Personally, I'm going to be wrapping all my .store/.carry methods with .booty and .plunder

[Maxion]

@artch said in Draft: Store prototype API:

• Store.getUsedCapacity([resourceType])

• • resourceType is undefined: equals to _.sum(store) with internal caching or null if this is not a general purpose store;

• • resourceType is defined: returns capacity for that particular resource or null if this resource cannot be stored in this particular structure

It might be a case of copy paste, or just me nit picking, but I think in that last list point of returns capacity for that particular resource it should be returns used capacity of that particular resource.

(and don't mind me not figuring out how to replicate the bullet list indentation properly)

[MrFaul]

• Store.getUsedCapacity([resourceType])

  • resourceType is undefined: equals to _.sum(store) with internal caching or null if this is not a general purpose store;

  • resourceType is defined: returns used capacity for that particular resource or null if this resource cannot be stored in this particular structure

Should really be:

• Store.getStored([resourceType])
  • resourceType is undefined: equals to _.sum(store) with internal caching or null if this is not a general purpose store;
  • resourceType is defined: returns stored amount for that particular resource or null if this resource cannot be stored in this particular structure

---

Store.getUsedCapacity([resourceType]) sounds more like you would get a float between 0-1 but you clearly want to return the actual amount.

[Thynosaur]

Hello,

I like this proposal in this current state. Code will be much simpler for many situations.

The only improvement I'd favour would be to change store.getUsedCapacity([resourceType]) to store.getAmount([resourceType]), favoring concision to regularity, MrFaul's store.getStored looks a bit redundant to me, but I like the rest of his definition.

[artch]

Remember that this method can (and in most cases will) be called without arguments. Store.getStored() or Store.getAmount() are not definitive enough in terms of "get how much capacity in this store is used for all resources in total". I'd say that Store.getAmount() without arguments should return an object with all resources rather than one single number of total used capacity.

[JBYoshi]

How about getTotalAmount()?

[deft-code]

What's the behavior of zero capacity Stores?

This happens when a Storage or Terminal has been RCL downgraded and with the loot Containers the caravans drop. It will also affect the Power Banks when they get a .store property.

Currently .storeCapacity is set to 0 for these structures. I assume getCapacity() will likewise return 0.

However as described now getFreeCapacity() will return a negative value. I did this in my own code and it caused all sorts of problems. I suggest the behavior be expanded to never return < 0.

[artch]

@deft-code Yes, getFreeCapacity is more like Math.max(0, getCapacity - getUsedCapacity)

[Thynosaur]

@artch said in Draft: Store prototype API:

I'd say that Store.getAmount() without arguments should return an object with all resources rather than one single number of total used capacity.

@artch I would say that Store.getAmounts() should return such an object. Store.getAmount() is "get the amount of whatever is in the store"

[W4rl0ck]

@thynosaur and that would be an object.. since there can be several types of resources in a store.

[MrFaul]

@artch How about Store.getStoredMass() couldn't get anymore clearer then that.

[Tessaryn]

Prolegomena: I'm a native English speaker.

getUsedCapacity reads pretty clear to me that you're getting a number that indicates how much of the store is used. Most other suggestions don't read as clearly as to what they represent.

[artch]

Implemented in this PTR patch.