Tags:

Utility Library

Author:

YangWenLi

Side:

Both

Created:

Mar 5th at 12:23 PM

Last modified:

Mar 6th at 3:07 PM

Downloads:

32

Follow Unfollow 23

Latest release (for Vintage Story 1.21.6, potentially outdated):
collisionflowfields.zip  1-click install

Back-Propagated Flow Field Collisions

A strange mod that adds weird collisions for questionable reasons.

This is an early release and has not yet been battle-tested in my mods. Use at your own risk.

 

This mod is meant to be a dependency for other mods, not a mod that is usable in itself.
To be clear: this mod does not add new collisions to existing game objects.

 

When developing Yang's Transport Tycoon, I had an issue: Since Vintage Story block collisions can't be larger than the extent of a block,
my 2x6 rail pieces could only be broken at a single corner, which was very unintuitive, and also allowed rails to clip through walls and each other.

Unwilling to compromise, I first looked into how the game handled multiple block span collisions, but found that the common approach was to either break
blocks into multiple pieces, to fake their collisions with invisible chiselled blocks, or to use the multi-block system which has limited support for complex/large shapes.

 

However, modifying the vanilla multi-block works would likely end in a performance and maintainability disaster, as well as damage compatibility with other mods.
So instead, I came up with the idea of 'Back Propagated Flow Field Collisions', a mouthful of a term for a rather simple concept.

 

 

Flow Fields can basically be explained as a grid where every cell points in a direction, that direction being the next cell
that has the most direct route to a discrete point in our grid. This means that if you follow the direction of any cell throughout our grid,
you'll always end up following the most efficient path towards our target cell.

This is a really efficient way of having a very large amounts of points in space which direct to the same goal.
Not only that, but they can be baked (we only calculate them once, instead of querying data each time we need it) as long as the target is static too.

This means that we can have blocks that hold an ultimate direction towards a source block, and as long as we overwrite their behaviour so that
they relay changes to their source, we suddenly have a bunch of separate, discrete blocks which act as one. All-for-one.

Of course, it's not enough for this to be a one-way relationship. When a change happens (like for example, we break one of our flow field colliders) and we
trace our way to the source block to relay the information, then the source block back-propagates the information to all the flow field cells pointing at it. One-for-all.

The key here is that our collision blocks are generic, they just relay data without themselves knowing who the source is, or being understood by the engine as part of a wider self.
This makes the blocks very efficient to store in memory, since they're just generic blocks like dirt or cobblestone. You can have millions of these blocks without barely any additional cost.
The real cost is offloaded to the processor, which has to iterate through our flow field and pass along data, and when back-propagating, potentially perform as many as twenty iterations,
a modern computer processor can roughly handle a couple million iterations each second assuming that each iteration consumes an abnormally inefficient amount of cycles to complete.

Thus, this set-up provides us with a way to create multi-block gestalts while keeping memory costs low and only intermittent (on demand) processor costs.
All for one and one for all.

 

Why Use BPFFC Over Multi-Block

You should not. In 99% of cases, the vanilla approach is superior (and better supported). It's why vanilla uses multi-block and not this.
This solution is only meant for the edge cases that multi-block refuses to handle, such as blocks larger than 5x5x5, or with complex shapes.

Case in point, if you need a chest, a door, a small raft, or any block that's small and can be shaped as a rectangle, use the vanilla multi-block.
But if for some reason you are tempting god by making blocks that have bendy-straw-like shapes or are very large in size, you can relegate yourself to my solution.
On paper BPFFC is also slightly more efficient, so if your block is meant to be placed in the thousands (like a rail would), then it's a reasonable fit too.

 

 

How To Use

I've made a short tutorial video here: https://www.youtube.com/playlist?list=PLD1qfOSzXxaTJvfVWHiSvNPfk0CFCUfDi

In summary:
1. Add the mod as a dependency to yours
2. Grab the authoring wand from the meta tab in the creative menu
then, left-click on your source block to select it.
3. From the same tab, grab the collision authoring blocks and manually build
out the colliders around your source block.
4. Once complete, right click with the wand, then check your client-main.log a code
block with the baked flow field values
5. Copy and paste the code block into your block's attributes
6. Optionally (not actually optional, do this), overwrite your block's CanPlaceBlock to check ModSystemCollisionFlowFields.CanPlace

You can check the "source" tab atop this mod page for the git repo of the mod,
which includes flowfield_sample_statue.json and BlockFlowfieldSampleStatue.cs, those two files contain all you need to know to use the mod.

 

 

This mod is brought to you by...

The Unofficial Vintage Story Modding Co-op, click here to join.
As modders, we can help each other make even better stuff. Plus we have dedicated channels for better organization.