UCD (Universal Cargo Dock) prototype proposal

[Megacrafter127]

UCD is a standard to allow transfering cargo between entities using docking. It is currently only a proposition based on a prototype, and thus needs some testing to confirm viability.

UCD will be based on USD for the dock itself, and as such this document will only illustrate how to transfer cargo given an already established dock.

Currently, the UCD standard specifies 6 item boxes and the requirements which the logic used to operate them must meet.
These 6 item boxes are hereby labeled as:

1. ParentSend
2. ParentTransfer
3. ParentCounter
4. ParentRecieve
5. ChildSend
6. ChildRecieve

The prefix of 'Parent' or 'Child' specifies in which entity the box is.
ChildSend and ParentTransfer are hooked up to the docking blocks.
The operating logic must fulfill the following requirements:

• ChildRecieve shall permanently pull exactly all items that shall be recieved through the dock from ChildSend.
• ChildSend shall pull all items that shall be recieved through the dock from the dock, if ChildSend is empty, while the entity is docked.
• ChildSend MAY also pull items that shall be sent through the dock from other storages on the ship whenever ChildSend is pulling items.
  
• ParentRecieve shall permanently pull exactly all items from ParentCounter.
• ParentCounter shall permanently pull exactly all items that shall NOT be sent through the dock from ParentTransfer.
• ParentSend shall pull all items that would be sent through the dock from ParentTransfer, exactly if there is NO entity docked.
• ParentTransfer shall pull all items that shall be sent or recieved through the dock from the dock and ParentSend, exactly if {[(ParentSend is NOT empty) OR (ParentCounter is NOT empty)] AND (an entity is docked)} OR (an entity docked AFTER the last storage-pull-tick)

Spoiler: Markup

BoxName
Pulling-condition
Itemfilter-condition

This will have the following effect:
Upon docking, ParentTransfer will be pulling items from both ParentSend, and the docked ChildSend. If ChildSend contains an item to send, it will be drained by ParentCounter once transferred, thus ParentTransfer continues to pull items.
Once ChildSend no longer contains items to send, it will be empty, causing it to pull items, while at the same time any item in ParentCount will be drained to ParentRecieve.
If ParentSend is not empty at this point, it will be emptied by ParentTransfer given enough time.
Once ParentSend and ParentCount are empty, ParentTransfer will no longer be pulling items, and thus allows ChildSend to pull the items the Child entity shall recieve through the dock.
Once pulled, they will be drained to ChildRecieve, freeing up ChildSend again.
This will continue until there are no more items to pull, at which point the transfer is complete.

There are 3 special cases:

1. The Child entity is trying to send items not accepted by the Parent entity.
   In this case, the child unloading phase won't properly end. A manual override switch on the Child entity will alleviate that issue. (the switch will force ChildSend to pull items, thus forcefully ending the unloading phase)
2. The Parent entity is trying to send items not accepted by the Child entity.
   In this case, residual items, that failed to be sent, will be left over in ParentTransfer. This however won't be an issue, as ParentSend will still be emptied, and drain the items back once the Child entity undocks.
3. The Parent entity has no items to send when the Child entity docks.
   The last part of the rules for when ParentTransfer will pull items specifically handles this case. It effectively acts as an automatic override, forcing the item-reception phase to start on the Parent entity whenever the Child entity docks.

Thoughts? Improvements?
Proof-of-concepts and a concrete simplified implementation are also welcome.

 

[Fellow Starmadian]

oh hey this thread is neat. Have you actually made a prototype for this? If not I'm available to build it. I AM working on my own stuff, but it's getting progressively easier to progress on own my personal projects the more I accept these directed jobs.
[doublepost=1493052976,1493052362][/doublepost]Maybe I misunderstand something, but this is far too complex for a universal standard. All you need for a universal cargo transfer is for each side to be able to tranfer blocks between each other, one storage for out and one for in. Plus each side has the option to accept or deny the transfer of cargo both ways. Why are there all these different commands?

Plus, the complexity with the accepting of certain resources gets messy very quick. can you specify how you plan to create an item white list / black list without placing the blame entirely on the sending entity for not filtering it's resources correctly?

what is parent counter?
[doublepost=1493053389][/doublepost]also, what is an item box

 

[Megacrafter127]

oh hey this thread is neat. Have you actually made a prototype for this? If not I'm available to build it. I AM working on my own stuff, but it's getting progressively easier to progress on own my personal projects the more I accept these directed jobs.

I did not make a prototype yet, however I know it is possible to build the system as it currently stands in starmade.

[doublepost=1493052976,1493052362][/doublepost]Maybe I misunderstand something, but this is far too complex for a universal standard. All you need for a universal cargo transfer is for each side to be able to tranfer blocks between each other, one storage for out and one for in. Plus each side has the option to accept or deny the transfer of cargo both ways. Why are there all these different commands?

This standard does not feature commands or wireless transmissions. It simply ensures that given sufficient time, the items that are designated as 'to be sent' are in the recieving 'box' of the other entity.
If my guess at what you are interpreting as commands is correct, they are just requirements the entityside system must fulfill in order to be 'UCD compliant'. They are just stating e.g: If X is the current state, ensure that storages A,B are pulling, while C is not pulling.

As for how an exchange will work, the 'This will have the following effect:' section below the markup spoiler will detail that.

As for why this is 'universal'. First, it can work with any docking connection, given the other entity is 'semi UCD compliant'. Aside from fully 'UCD compliant' systems, a UCD compliant parent entity will also be able to handle the following two cases:

1. Dumping-dock
   The child is set up such that all items in its dock-connected storage are supposed to be removable(just hook up a disabled storage to the rail docker). A UCD compliant parent entity will be able to service such a child entity, to the limits of its whitelist of accepted items. [see special case 1]
2. Filling-dock
   The child is set up such that it sucks all whitelisted items from the parent-entity's dock-connected storage into its own storage(just hook up a pulling storage to the rail docker). A UCD compliant parent entity will be able to service such a child entity.

Plus, the complexity with the accepting of certain resources gets messy very quick. can you specify how you plan to create an item white list / black list without placing the blame entirely on the sending entity for not filtering it's resources correctly?

For the child entity, it is simple. All resources found in the box 'ChildSend' on docking are up for being transferred away. As for which resources to accept, the item-pull-filter in the same box filters that. However, the filter on the 'ChildRecieve' box should be identical, otherwise the items might end up being transferred away again at a later dock.

As for trying to send invalid items, see special cases 1 and 2.

what is parent counter?
[doublepost=1493053389][/doublepost]also, what is an item box

ParentCounter is an item box.
Item box is synonymous with storage within this definition.

 

[decurr]

I actually had created a simplified system a few months ago. It used less blocks. But I thought I would improve it to meet the conditions set out here. Unfortunately, the last update broke it.

I was using a simplified USD (the station did not need a docking module) so everything was going through one docking set and only items specifically set to be pulled. This prevented items from being pulled back and forth through the dock. Now it no longer works so having both docking sets (so a true USD) is required.

It seems that the logic that checks whether a storage is empty or not is also broken. I need to do more testing to see if there is another way.

Now for some questions, or at least some things to think about:
1. Is it intended for this system to be completely automated? How does lets say the parent determine what items get sent to the child?

2. In one scenario, there is a station refinery(parent) and a mining ship(child), appropriately outfitted, they work as anticipated in UCD fashion. A second scenario, the same station refinery(parent) and same mining ship(child) but are far apart. Now a freighter(child) is utilized to transfer from mining ship to station. Does the mining ship need to also have the parent parts? As this is just a cargo dump situation, perhaps not. Then what about a station A -> freighter A -> freighter B -> station B situation?

3. Does each entity (parent or child) only get one set of cargo handling and just link to all docks or does each dock get its own set of dedicated cargo handling?

All in all though, this sounds like something we should have. If we ever get AI freighters that can haul goods between faction (or even allied) stations, this UCD system would be needed. If you are using USD, then having a UCD capability makes sense. Especially since it seems we cant agree on a cargo container standard.

 

[splatthecat]

I have yet to got as I have yet to decide.

It started well but I drifted off midway through the description.

Three of the five different cargo systems that I normally use (four pods of various sizes and a cargo drone) use USD compatible docking. I find it more convenient and lots of people already build with USD in mind.

While the concept of UCD is sound, the reality seems a little over complicated.

 

[Megacrafter127]

It seems that the logic that checks whether a storage is empty or not is also broken.

If such storage logic is currently broken, that is a bug. Unfortunate as that is, we should be able to expect it to be fixed within a reasonable time. Automating any inter-entity cargo transfer without utilizing manual interaction or precise predetermined timers is impossible without being able to detect if a storage is empty or not.

1. Is it intended for this system to be completely automated? How does lets say the parent determine what items get sent to the child?

UCD is intended to be completely automated, safe for the establishment of a docking connection, or a special case requiring player intervention. (currently only 1 such case exists, and it is not a 'fatal' case[meaning the system can recover from it after undocking even if no intervention occurs])
As for the specific question of how the parent determines what items get sent to the child:
In the current specifications, all items that are contained in ParentSend will be sent to the child, UNLESS the child is unable to process them[a.k.a does not pull such items in any case]. Parent and Child can only offer items[although a fully compliant parent is expected to be able to process any item(any recieved item that it is trying to send will be added to ParentSend after undocking)], whether an offered item is transferred depends on whether the other entity accepts it.

2. In one scenario, there is a station refinery(parent) and a mining ship(child), appropriately outfitted, they work as anticipated in UCD fashion. A second scenario, the same station refinery(parent) and same mining ship(child) but are far apart. Now a freighter(child) is utilized to transfer from mining ship to station. Does the mining ship need to also have the parent parts? As this is just a cargo dump situation, perhaps not. Then what about a station A -> freighter A -> freighter B -> station B situation?

A docking connection, at least as currently implemented in the game, will ALWAYS have a parent and a child. The parent is the entity with the rail on which the rail-docker of the child is docked. As such, two entities that can only act as UCD Child-entities will not be able to establish a docking connection.
The parent and child storages of the same entity can easily be integrated into another. ParentSend is also capable of acting as ChildSend, and so can ParentRecieve act as ChildRecieve. This however assumes that the entity cannot be docked as parent and child simultaniously.
To answer the question, freighter A/B can only dock to freighter B or the miner, if either assumes the role of the parent. Which it is does not matter, however I recommend the smaller being the child, due to space restrictions, but it is not specified in the standard.

3. Does each entity (parent or child) only get one set of cargo handling and just link to all docks or does each dock get its own set of dedicated cargo handling?

As pure child entities can only ever dock to a single parent at a time due to game mechanics, it has no effect if the child UCD setup serves a single or multiple rail-dockers.
So long as the parent only has 1 child at a time, the same goes for parent entities. As for multiple children, while I did not test anything[hypothetical or ingame] yet, I predict that having 1 UCD storage setup serve multiple children will slow the transmission down due to state desynchronizations between the children. However as the current specifications cause UCD to self-synchronize its state given sufficient time, assuming the parent is fully UCD compliant(can process any recieved item) the parent will still serve all children given enough time. Any new child docking will further delay that process.

Three of the five different cargo systems that I normally use (four pods of various sizes and a cargo drone) use USD compatible docking. I find it more convenient and lots of people already build with USD in mind.

Could you please specify those systems? UCD may turn out to be backwards compatible to them.

 

[Fellow Starmadian]

Reading your posts makes me introspect on the length of mine.

 

[splatthecat]

Could you please specify those systems? UCD may turn out to be backwards compatible to them.

They are the ones I have developed and need to get round to sharing.

The only exceptions are the custom pods used on my ASI Isanth-VI Jump Cargo and my 5x5x5 Cargo Drone.