Grid Framework [scripting and editor plugins]

DrEvizan · Sep 25, 2019

Thank you. In retrospect that answer was pretty obvious but thanks for leading me there anyway!

VectorNector · Jun 6, 2020

Hi,

I’m messing with the sliding puzzle example and I want to add another axis to the game’s mechanics so that the blocks can slide on all 3 axises. What do you suggest doing?

Thank you!

hiphish · Jun 6, 2020

VectorNector said: ↑

...
Click to expand...

Hello,

The code should work the same, the tricky task will be to actually come up with a good way of moving blocks in a 3D environment using 2D controls. Moving blocks by itself has nothing to do with grids, so I would suggest that you first find a way of moving blocks free-form (no snapping), and once you have that working you can apply the snapping code from the 2D puzzle and it should work the same.

VectorNector · Jun 8, 2020

hiphish said: ↑

Hello,

The code should work the same, the tricky task will be to actually come up with a good way of moving blocks in a 3D environment using 2D controls. Moving blocks by itself has nothing to do with grids, so I would suggest that you first find a way of moving blocks free-form (no snapping), and once you have that working you can apply the snapping code from the 2D puzzle and it should work the same.
Click to expand...

Hi HiPhish,

I see what you're saying. I was thinking about using an isometric view to make everything work. Now I understand that it's about getting the controls down first.

I appreciate your help. Thank you so much!

stansison · Sep 5, 2020

Hi, I just upgraded my app to URP. I’m using a parallelpiped with the GridFramework/DefaultShader. The mainCamera is equipped with a Grid Camera. The plugin was working with no issues before the update to URP. But after the update, the grid is no longer showing during runtime.
How should I modify the defaultShader to work with URP or perhaps is there a specific setting to make it?

Edit: Visiting the sample scenes, none of the grid lines are appearing either. Grids still appear in the scene/editor mode.

hiphish · Sep 6, 2020

stansison said: ↑

Hi, I just upgraded my app to URP. I’m using a parallelpiped with the GridFramework/DefaultShader. The mainCamera is equipped with a Grid Camera. The plugin was working with no issues before the update to URP. But after the update, the grid is no longer showing during runtime.
How should I modify the defaultShader to work with URP or perhaps is there a specific setting to make it?

Edit: Visiting the sample scenes, none of the grid lines are appearing either. Grids still appear in the scene/editor mode.
Click to expand...

I think this is the source of the problem:

URP does not currently support custom post-processing effects. If your Project uses custom post-processing effects, these cannot currently be recreated in URP. Custom post-processing effects will be supported in a forthcoming release of URP.
Click to expand...

https://docs.unity3d.com/Packages/c...l@8.2/manual/InstallingAndConfiguringURP.html

The lines do not belong to any mesh, they are generated on the fly during runtime and rendered in the OnPostRender method. You could either wait for URP to implement post processing effects, or use Grid Framework to generate a mesh at runtime and render that one. If you want to use the latter, it's not trivial, but you can contact me via PM and we can work out the necessary code. Generating a mesh from data is also how Vectrosity renders vector lines, so it's not an outlandish idea.

stansison · Sep 8, 2020

Thank you for the update Hiphish. I’d like a solution, but I think it would better serve both our times to wait for URP to get to that stage instead of creating a bandaid fix.

For now, I’ll just roll back the URP updates. Hopefully they fix post processing first before they make URP the standard.

ssssxxxxdddd · Oct 14, 2020

Hi, do you think this would work for making an oblique/cabinet projection 2d game? I am struggling to find any way to change my grid from something other than iso/hex

hiphish · Oct 15, 2020

ssssxxxxdddd said: ↑

Hi, do you think this would work for making an oblique/cabinet projection 2d game? I am struggling to find any way to change my grid from something other than iso/hex
Click to expand...

Are you using a 2D game project or a 3D game project?

Yagolov · Nov 25, 2020

Hello!

I am not a coder and I bought the asset yesterday because it supports PlayMaker.
I have read the information, watched the videos on youtube and went through few pages of the forum and...
I still can not figure it out how to make the conection between the Grid and the Game objects.
I am sorry if it is really wide my questiion... but after lots of hours trying my best I think it would be great if someone could throw me some light.

What I want to achieve is creating an hexagonal grid (I already have created it and added the Scripts and the Mesh collider) and then placing different game objects that snaps in the already created grid. I really would appreciate if you/someone could help me out in this noobish question about how I should approach this.

The concept it is similar to Chess. A grid with different objects that moves within the grid using mouse clicks.

Thank you !!

hiphish · Nov 25, 2020

Yagolov said: ↑

...
Click to expand...

Hello.

You don't make a direct connection between your objects and the grid. What you do instead is something like this:

Get the world position of your object (store inside a Vector3 variable)

Convert it to grid coordinates (another Vector3 variable)

Do some math on it, such as rounding the individual values if you want to snap an object, or add another vector if you want to move the object; the result is another Vector3 coordinates

Conver the (new) grid coordinates back to world coordinates

Move your objec to the new world coordinates.

So if you had a chess game and you want to move the bishop two fields diagonally, you would take the bishop's grid position, add the vector (2, 2, 0) to it, convert the result to world coordinates, and animate the bishop's movement.

This is the basic pattern of using Grid Framework for moving objects in the world. When you write code you can wrap those five steps behind one method to hide the complexity, not sure how Playmaker handles complexsity. I hope my explanation makes sense to you. Let me know if it doesn't.

Yagolov · Nov 26, 2020

Hello,

Thanks a lot!
I struggled but you provided me the guides that I really needed.
Much appreciated!

lsotero · Dec 8, 2020

Hi there, I have searched quite a lot and haven't found a way to do so. I know it uses GL to draw at runtime but I really don't have much knowledge on the rendering part, but it doesn't matter what I do, it always draws on top of everything? I'm trying to mix it with sprites and it's ALWAYS on top of every single sprite I place in, doesn't matter what I try to change, is there a way to actually use the renderer like that? I think I even remember seeing something like this draws Lines and not Surfaces, but do I require it to be a surface in order to Z sort them for sprites?

hiphish · Dec 9, 2020

lsotero said: ↑

...
Click to expand...

Hello,

Can you please provide me some more information? Are you using a 2D or a 3D project? Can you please provide a screenshot (PM me if you don't want it public)? I first need to reproduce the issue on my end.

lsotero · Dec 9, 2020

hiphish said: ↑

Hello,

Can you please provide me some more information? Are you using a 2D or a 3D project? Can you please provide a screenshot (PM me if you don't want it public)? I first need to reproduce the issue on my end.
Click to expand...

I sent you a pm

hiphish · Jan 8, 2021

Plans for Grid Framework 3.0

I intend to release a new major update which will address among other things the grid rendering system. It has been almost five years since the release of version 2.0, and Unity has changed quite a lot in this time. Some of those changes, in particular the introduction of sprites, need to be accounted for in Grid Framework.

This will be a major update which breaks backwards compatibility. Some breaks are necessary, some will simply be me cleaning up minor bumps while I'm at it. But all in all I expect the changes to be small, much smaller than between 1.0 and 2.0.

The upgrade will be free for existing customers since it will be basically just a maintenance release.

Upcoming changes
Rendering grids
Unity is a 3D game engine, it primarily renders 3D game models. There is an escape hatch provided by the GL class, but lines drawn that way appear on top of sprites, even if the sprite is in front of the grid in the scene. This is simply not acceptable, but this way of rendering grids has big advantage over any alternative approach, so getting rid of it is not an option either.

Let's take a step back for a moment. C# is an object-oriented language, and the point of object-oriented programming is interfaces and messages: the program consists of a graph of objects which communicate among each other by sending messages. The important part is not what class an object has, the important part is what public interface an object exposes, which messages it can receive. We can at runtime swap out one object for another object as long as both expose the same interface, regardless of how they implement that interface.

Following that logic, why should there be only one way of rendering a grid? I wish to expose a generic rendering interface and allow users to plug in their own backend of choice. Some default implementations will be included, but users will be able to create their own implementations as well. Here are my planned implementations so far:

The already existing GL implementation

A new implementation which generates a mesh with Lines topology

A Vectrosity backend, which will be basically the already included Vectrosity support, but rewritten

Different backends have different strengths and weaknesses. For example, Unity renders the lines of a mesh with Lines topology always at the same width, and there is nothing I can do about that, but in return you can use all the shader features of Unity and lines will appear behind grids. For some people that might be exactly what they need.

The main change between version 1.0 and 2.0 was breaking the huge grid classes into small grid classes and separate render classes. This has proven to have been a good choice and has allowed users to create their own grids very easily. I know one customer who has created a custom grid which looks like the wires of a guitar (the horizontal lines are not parallel and the distance between vertical lines keeps increasing). I hope that this change will empower users similarly.

No more included examples
Grid Framework comes with a number of examples included to get you started. When I had originally submitted Grid Framework to the Unity Asset Store I was asked to provide an example or two because it wasn't really clear what my asset was doing. Since then the number of examples and their sophistication has grown, and Grid Framework has been established.

Bundling these examples nowadays just adds bloat to people's projects. Sure, you can just delete them (they are all in one common directory), but then you have to do so after each update. For 3.0 I want to move the examples to a separate project that can be hosted in public. It would also allow people to see the API in action before they make a purchase.

Minimum Unity version required
I have not yet settled on a definitive version, but I will certainly increase the requirements. This will allow me to make use of more recent C# features and keep the code leaner.

Time frame
I do not have any estimate on when 3.0 will be released. The changes to the code are not large, but I have to get the API right the first time. How should the user hook up the rendering backend to the engine? Should I allow multiple backends at the same time? Where should newly created GameObjects and components be added to the scene?

I hope to release 3.0 somewhere during the first quarter of 2021, but time will tell.

stansison · Jan 28, 2021

I came to check here to see if there would be news about URP compatibility. This update sounds amazing. Looking forward to it.

hiphish · Apr 25, 2021

Version 3 reaching feature parity with version 2
Grid Framework version 3.0 is coming along nicely, I have reached feature parity with the previous major release. This means that the heavy refactoring is mostly done and I can now build upon that foundation. I want to take this opportunity to reflect on what will change.

The rendering system
The first two major releases of Grid Framework had a very naive idea of rendering: there was only one primary way of rendering a grid and Vectrosity support somehow wedged in there, but stuck out like a sore thumb. For version 3 I want to have a proper rendering system that many objects can access in a uniform way, which will make it possible to ship with a reasonable default set of backends and allow anyone to write their own custom rendering backend. Here is a rough sketch of how it works:

Code (csharp):

+------------+ +------------+ +--- ---+ +------------+

| renderer 1 | | renderer 2 | | ...... | | renderer n |

+------------+ +------------+ +--- ---+ +------------+

| | |

| | |

| | |

+----------------+------------ ...... -------------+

|

|

V

+------------------+

| rendering system |

+------------------+

The rendering system acts as a mediator between the renderers and other objects which want to receive grid points. These rendering backends do not need to know about all the renderers in the scene, renderers automatically register and unregister themselves with the rendering system. This provides decoupling between renderers and backends and leaves the two with only one narrow interface between them.

Currently there is only one backend which renders the grids using Unity's low-level
GL
class; this is the same backend we have in version 2 as well. The next backend with be mesh-based: it will generate a mesh for each grid and let Unity handle rendering that mesh.

Performance considerations
The original rendering implementation had a massive memory leak problem: I was allocating an array for every grid every on frame and throwing the old array away. This was not much of an issue because C# is a garbage-collected language, but the large amount of garbage was hitting performance really badly for large grids.

I solved the issue by introducing a caching feature in the implementation where I store the array of points and as long as the points have not changed I can just send out the same points again. If the points have changed, but not their amount I can mutate the existing array instead of allocating a new one. Only if both the points and their number have changed to I have to compute them from scratch. You can read more about it in this old post.

This is good enough for the existing
GL
backend which has to redraw the grid on every frame anyway, but it will not do for a backend which generates a mesh. If we generate a new mesh on every frame we are right back where we started with the garbage problem. For this reason the rendering system delivers also needs a mechanism which indicates to the backend whether the points have changed since the last query.

Breaking OOP best practices
My original plan was for renderers to push changes to the rendering system and then have the rendering system notify the backends. The system would keep track of both the renderers and the backends and implement an observer pattern. I had to scrap the idea though because there is no way in Unity to get notified when the
Transform
of an object changes.

The rendering system is a static class rather than an actual object. Proper OOP best practices shun static classes because a static class with mutable members is really just global state in disguise. You cannot mock it and you cannot inject it as a dependency into an object.

This is one instance where pragmatism wins over theory. Unity's
MonoBehaviour
class does not provide me with constructors for dependency injection and there is no god-class which could instantiate a rendering system object. It is not as bad as it might sound though, it just means that instead of testing one class at a time I might have to test two classes at a time, which is something I can live with.

Removing the event system
Speaking of pragmatism, I have decided to remove the grid event system. It was originally put into place in order to make the renderers lazy: there are a number of private cached member variables inside each renderer which only need to be updated when the grid changes. Using C# events I had set up a system where mutating a grid property would fire off the event and trigger the renderer to compute the cached members anew.

For example, I had the following code in the
RectGrid
class (documentation comments omitted):

Code (CSharp):

public class SpacingEventArgs : System.EventArgs {

private readonly Vector3 _difference;

public SpacingEventArgs(Vector3 previous, Vector3 current) {

_difference = current - previous;

}

public Vector3 Difference {

get {

return _difference;

}

}

}

public event System.EventHandler<SpacingEventArgs> SpacingChanged;

[SerializeField] private Vector3 _spacing = Vector3.one;

public Vector3 Spacing {

get {

return _spacing;

}

set {

var oldSpacing = _spacing;

_spacing = Vector3.Max(value, Vector3.one * Mathf.Epsilon);

if (SpacingChanged != null) {

SpacingChanged(this, new SpacingEventArgs(oldSpacing, value));

}

}

}

Another script could then subscribe to this event:

Code (CSharp):

RectGrid grid;

// Write some actual logic instead of logging a message

grid.SpacingChanged((sender, args) => Debug.Log("Spacing has changed"));

In the end it was not worth the effort, it just bloated up the API with new classes. The new code simply compares the current value and the previous value whenever a computation is issued by the renderer. If Unity classes were meant to be used in a reactive way they would have reactive APIs.

Next steps
The next big step is to get the rendering system to work well with multiple backends and then to write those backends. Once everything is working and in place I can finish the documentation and scan it for any ugly warts that might still be out there to remove them.
Click to expand...

hiphish · May 9, 2021

Mesh-based rendering

The big one has landed: mesh-based rendering. This is the main reason for the major version bump and it is fully working now. Mesh-based rendering means that instead of drawing lines using the low-level GL class a mesh is generated which Unity can then render the same way it renders any other mesh. This means that grid lines can now be rendered below sprites instead of always on top of them.

How it works
The mesh-based rendering backend needs to be attached to a game object. It then queries the rendering system periodically for changes. Only when a change has occurred the mesh is re-computed. This helps us save processing power and keeps garbage low. Usually a mesh is made up of triangles, but in this case I use the lines topology, which lets us draw a mesh made up of line segments.

Ideally the backend would get notified automatically when a grid property has changed, but this is unfortunately not possible in Unity. Instead the backend asks the system every frame “Check if anything as changed”, then the rendering system does its stuff, and eventually it sends a notification back to the backend if there is something to be done. Currently the system is queried on every frame, but it would be easy to add a variable to only query on every n-th frame.

Drawbacks
All lines have the same colour and a width of one pixel. I could implement different colours per axis, but I do not think there is interest in such a feature when rendered in a running game (it is useful in the editor view though). As for the line width, I think this is better left to a 3rd party package like Vectrosity.

I prefer not to add everything and the kitchen sink, other people have already solved the problem of rendering lines much better. Grid Framework should come with rendering solutions which are good enough for the basic uses cases, and make it easy to integrate with other packages if users desire more features and control.

Next steps
I need to migrate Vectrosity support to the new system and maybe change how it is used. Ideally I would like to extract Vectrosity support to into its own package to download from the Asset Store (for free of course) so it does not bloat the rest of Grid Framework for those who do not need it. However, this will depend on whether the Asset Store allows uploading packages which have dependencies on a package which I do not own.
Click to expand...

EmeralLotus · May 9, 2021

hiphish said: ↑

Mesh-based rendering
Click to expand...

Amazing work. Huge win for everyone.
Instead of Vectrosity, there is an incredible, Zero GC allocations line package that we are using.
Request, can Linefy be supported.
https://assetstore.unity.com/packages/tools/particles-effects/linefy-165393

hiphish · May 9, 2021

EmeralLotus said: ↑

Instead of Vectrosity, there is an incredible, Zero GC allocations line package that we are using.
Request, can Linefy be supported.
https://assetstore.unity.com/packages/tools/particles-effects/linefy-165393
Click to expand...

I am aware of Linefy and I would like to support it eventually, just not at launch. The possibility of supporting Linefy (and any other future framework) is why I want to clean up the interface and make it as easy as possible to hook up anything. But I want to keep the scope of the initial release of 3.0 focused on what we already have so I can release it sooner rather than later.

hiphish · Jun 29, 2021

Vectrosity rendering backend

I have finished the rendering backend for Vectrosity and updated the included examples to use it. Previous releases already came with an extension method that let you get the list of points to construct a vector line, but the actual construction of the vector line was up to the user.

The included example has several grids, among them is a bouncing grid which moves over the place but keeps its shape, and a resizing grid which does not move, but keeps changing its shape. Both types need to construct a vector line, but the lines had different properties, so each one had a custom ad-hoc script.

The new Vectrosity backend puts an end to this ad-hoc hackery: all you need to do is add one component to your object, set the properties to your liking and it will work. Of course the more low-level extension method still remains so you can implement your own backends. The example includes one grid where the colour of each segment of the vector line changes randomly, creating a very cool and flashy effect.

In the above picture the green (polar) and red (rectangular) grids are bouncing all over the place, while the yellow (hexagonal) grid keeps shrinking and expanding its radius. The rectangular grid in the upper left-hand corner is rotating around its centre while its line segments keep randomly shifting their colour. The bouncing, resizing and rotation are separate scripts not tied to the rendering backend.
Click to expand...

EmeralLotus · Jun 29, 2021

hiphish said: ↑

Vectrosity rendering backend
Click to expand...

Very Cool

hiphish · Jul 11, 2021

Embracing the Unity package system

When I released version 1 and version 2 of Grid Framework there was no real way of separating libraries. You had to dump everything into your project in one assembly. Using namespaces prevented name collisions, but you still had things like examples or documentation bloating up your project and there was no way of expressing dependencies. Since then Unity has introduced its own package system, which will solve many of the problems I have had in the past.

Since version 3 is a major upgrade, I am dropping backward compatibility with prior versions of Unity, which means that I now have the opportunity to make Grid Framework a proper package. A package allows me to do the following:

define metadata (like version number) which will be available in Unity

separate runtime scripts and editor scripts into distinct assemblies

separate examples from the actual library

Packages can be distributed in different ways, including as a public Git repository. This solves the massive thorn in my side that is Vectrosity and Playmaker support. If someone does not have either of those dependencies they would get compilation errors. My solution so far was to wrap the code inside #if preprocessor directives, but this required people to define extra preprocessor symbols in their project and it would still bloat Grid Framework for anyone who did not need those integrations.

With packages the solution is simple: I can just implement each integration in its own package and make it available as a public GitLab repository. There is no need to go through the Asset store for something this simple. It also means that other integrations could easily be published without having to update the main package.

This only one problem: the documentation. It appears that Unity wants package documentation to be either one Markdown file or a link to some online documentation. The former may be appropriate for something simple, but not for a library this large. The latter is unacceptable in my opinion, if your internet broke down you would be stranded without any documentation. I will have to see what can be done. At least I will no longer have to rename all the images and generated Javascript files to prevent Unity from importing them as game assets.
Click to expand...

hiphish · Aug 1, 2021

Vectrosity support as a package

I have completely transitioned Grid Framework to a Unity3D package now and moved Vectrosity support to a separate package. The Vectrosity package will be made available as a public Git repository under the MIT license, that should make it as simple as possible for users to add it to their project. While transitioning to packages has had many advantages there have also been some challenges to overcome and I would like to go over them in this post.

Documentation
I hold the opinion that every software should come with offline documentation, unless it is so trivial that it does not need any documentation to begin with. The manual and scripting reference consists of HTML pages with images, CSS files and a little bit of JavaScript, all generated by Doxygen.

The result is pretty good in my opinion, but Unity throws a wrench in my plans: it treats the Javascript as game scripts and the images as textures. Now your project won't compile and your textures library will be full of images which were never meant to be used as textures. My solution until now has been to run some automated text editing magic to rename the files and rewrite references to them. It works because the web browser does not care about file extensions when rendering a page, but you might have issues if you try to open the image on its own.

Packages solve this problem neatly: Any directory name which ends in a tilde (~) will be ignored. Unity already uses Documentation~ for documentation, so I simply output the generated files there. A README file points users in the right direction if they decide to poke around in the folder, and the documentation can be opened straight from Unity's help menu as well.

Samples
Examples are a good way to get a taste of an extension in action and try it out quickly, especially for a scripting extension. The examples have had a similar problem to the documentation in that you would have all those foreign textures and scripts in your project, but at least examples would not stop your project from compiling. Users who did not want all that stuff had to go and delete the examples by hand. We can do better than that.

Packages have a "samples" mechanism: you can mark certain directories of the package as samples and users can then import individual examples into their project. They can also throw the imported sample away or modify it without affecting the original sample. Samples are usually stored inside the Samples~ directory which is ignored by Unity.

That's great if you are a user, but it is horrible if you are developer. I do not want Unity to ignore my samples, I want it to compile my scripts, load my textures, generate meta files and so on. After trying out various solutions, one more convoluted than the other, I think I have found a dead simple and in hindsight obvious solution: use symbolic links (symlinks).

First I symlink the original samples directory to one that is not ignored: ln -s Samples~ Samples. This creates a directory which Unity will pick up, and changes to files inside the link directory are applied to the files inside the original directory (because they are the exact same files). All that is now left to do is to instruct Git to ignore the link by adding the link to the .gitignore file (or to .git/info/exclude). Obviously the link must not be shipped to end users.

A final word of caution: Unity warns against using symlinks because it is possible to seriously mess up your project. They do not discourage it, but you need to know what you are doing.

Packages/com.hiphish.grid-framework/Samples is a symbolic link. Using symlinks in Unity projects may cause your project to become corrupted if you create multiple references to the same asset, use recursive symlinks or use symlinks to share assets between projects used with different versions of Unity. Make sure you know what you are doing.
Click to expand...

I think I'm going to be fine. What could possibly go wrong? (famous last words)

Vectrosity package
This is the big one. Including Vectrosity support in the main package would break compilation for anyone who does not have have Vectrosity installed, so I needed an ugly workaround involving preprocessor symbols. With packages it's simple: if you want Vectrosity support, install it as a separate package. The package will be available on launch as a public Git repository, no strings attached.

There are two ways to create a package: as a standalone package or embedded inside a project. Grid Framework is embedded because it is simpler to have the supporting Unity structure around it. The Vectrosity package on the other hand is standalone because it makes things easier for users.

However, in order to develop Vectrosity support I still need a Unity project to generate the meta files and provide me with tooling while programming. The solution is simple: First I have a copy of the Git repository on my local system, then I add it as a local package to my Grid Framework project. I can now work inside the Grid Framework project, make changes to the Vectrosity files and the original files inside the Vectrosity repository will be affected.

I also use the same trick for working on the samples as above.

Conclusion
Unity packages solve many of the issues of the past: files can be grouped properly according to their role, directories can be ignored, scripts can be compiled in separate assemblies, and packages can have metadata. They also introduce their own sets of challenges, but the new problems are far easier to solve and can be solved cleanly instead of hacking my way around them.
Click to expand...

hiphish · Sep 11, 2021

Git packages or embedded packages? Yes.

In my previous post I wrote about how I maintain the optional extra packages to Grid Framework. Since this point is useful for working with Unity in general I think it's worth elaborating upon the topic in a separate post.

The different kinds of packages
There are three different kinds of custom packages:

embedded packages

local packages

Git packages

An embedded package resides inside the project itself, where it is contained within a directory inside the Packages directory. Embedded package have the advantage that their code is actually part of the project and as such we can work on the code directly. As such our code tooling (like Omnisharp or an IDE) can operate on the code of the package. Embedded packages cannot be shared among projects.

A local package resides within a directory on our file system but outside the project. Local packages can be shared among projects and we can work on their code, but we cannot do so within the context of a Unity project. This is not much of a deal if our package does not contain code though.

A Git package is a Git repository, usually on a remote server. Git packages are ideal for sharing a project among multiple machines, but we cannot work on them directly. Of course we can clone the repository and work on it, but we cannot work on the original package directly. Git packages are great if we want to make the package distributable.

The problem I want to solve
My addon packages have two target audiences: me as their developer, and you as their end users. I want the packages to be as easy to install as possible, so a Git package is ideal. I can tag individual releases and users can then choose which version they want.

On the other hand the packages contain code and I need to work on it. For this purpose an embedded package would be ideal. Yet I still need to be able to tag releases and switch branches without having to affect all of Grid Framework. There is no reason I should have to branch off the entire project just because the add-on has an issue.

Git submodules give us the best of both world
Git has a feature called submodules, which lets us put Git repositories inside Git repositories. Normally we should use a proper package manager for managing dependencies, but sometimes a submodule is exactly what we need. In our case we want the remote package to be stored inside the Unity project as if it were a local package. Fortunately Unity does no require any different file structure or metadata for the different kinds of packages.

Assuming we are in the repository of the project we can add the submodule using this command:

Code (csharp):

git submodule add <path-to-origin> Packages/com.hiphish.grid-framework.playmaker

git submodule add <path-to-origin> Packages/com.hiphish.grid-framework.vectrosity

The last parameter is important, it tells Git under which path to save the repository. This is effectively it, we can now use the package in our project, we can cd into the submodule and work there. We will probably want to set up which branch to follow, so we can execute the following in our shell:

Code (csharp):

git config -f .gitmodules submodule.source/Packages/com.hiphish.grid-framework.playmaker.branch master

git config -f .gitmodules submodule.source/Packages/com.hiphish.grid-framework.vectrosity.branch master

Or add a branch entry to our .gitmodules file inside the main repository:

Code (csharp):

[submodule "source/Packages/com.hiphish.grid-framework.playmaker"]

path = source/Packages/com.hiphish.grid-framework.playmaker

url = git@gitlab.com:HiPhish/grid-framework-playmaker.git

branch = master

[submodule "source/Packages/com.hiphish.grid-framework.vectrosity"]

path = source/Packages/com.hiphish.grid-framework.vectrosity

url = git@gitlab.com:HiPhish/grid-framework-vectrosity.git

branch = master

Conclusion
TL;DR: Make your package a Git repository, add it as a Git submodule to your main project repository and make sure to set the correct path so Unity sees it as an embedded package. Work on the copy inside your main project, commit and tag there, then push to the origin. Users can use the origin as a Git package in their own projects. For more information refer to the official Git documentation: git help submodules
Click to expand...

hiphish · Sep 14, 2021

Playmaker actions overhaul

Let's have a mental exercise: image something shameful you have done, it doesn't have to be the most shameful thing, just something that you really are not proud of should do. Now imagine putting it in a sealed box where it will be rotting and festering for years. Now imagine having to open that box, slowly lifting the lid as the rancid smell starts creeping out of the box. That is how it felt when I opened up the old Playmaker support.

I added Playmaker support due to popular demand and it should have been really simple on paper: just provide actions which correspond to the classes and methods we have. The problem is that I made a separate action for every single thing you could possibly do. Want to get the radius of a polar grid? That's one action. Want to get the angle of the same grid? That's another action. Want to also set those two properties? That's two more actions. With how many possible combinations of properties and methods there are, you can easily imagine how it spiraled out of control very quickly.

The new actions
I don't remember why I did it that way. Maybe it was the only way back then? Or maybe I just didn't know what I was doing. Anyway, I decided to clean up real good and merge actions which actually belong together. Getters and setters are still separate actions, this is also how the official Playmaker actions work.

Grid property accessors
Grid property getters are simple: they just read the property from a grid object and make it available. All properties of a particular grid class have been merged into one action per grid class. If we don't care about a particular property we can simply ignore it.

Grid setters are a bit more complicated. For starters not all properties are writeable, so some setter actions have fewer properties than their corresponding setters. There is another problem though: what if we do not want to set a particular property? This is where Playmaker variables come into play: if a field is set to a variable, but the variable is None, then the field is ignored and not set. This allows us to store all setters in one action, but still retain the ability to pick and choose which setters to actually run.

Coordinate conversion methods
The meat and potatoes of Grid Framework. For every grid class there is one action with four fields:

the input value

the output value (a variable)

The source coordinate system (an enum)

The target coordinate system (an enum)

This slightly increases the size of each action, but it cuts down the number of actions drastically.

Conclusion
At present there are 28 individual actions. Out of those four are for conversion, so that leaves 12 getters and setters each. That's still a lot, but it is a far cry from the original count of 104 individual actions. Yeah, I'm really not proud of that one, but now is the opportunity to make up for it and get it right.

Click to expand...

hiphish · Sep 20, 2021

Playmaker samples

The new overhauled Playmaker bindinds will be shipped as a separate package, so this lets me finally implement a great jumping-off point for new users: included samples. The following samples are now included and can be individually added to or removed from your project:

Create grid: starting from nothing we create a new game object, add a grid component and a renderer component to it, and finally set some properties. This example walks you through all the steps necessary to create and set up a new grid and make it visible in-game.

Convert coordinates: coordinate conversion is the bread and butter of Grid Framework. In this example we have a grid set up and a Vector3 variable which represents a position in grid-space. We convert the value to world-space and use the result to instantiate an object in the scene.

Resize grid: actions do not have to be a one-off deal, you can run them every frame. This example uses Playmaker's own float animation action to smoothly transform a floating-point value every frame. We then feed that value back into the radius property of a polar grid to make it grow and shrink in real time, creating a pulsating effect.

Including these samples would have been impossible if I were to ship the Playmaker bindings with the core package. Each example carries a Playmaker FSM (finite state machine) instance, which requires Playmaker classes to be available at compile time. However, by moving Playmaker support to an external package I can now include samples without any issue.

These included examples provide you with working minimal examples. You can see how to set up a FSM and you can experiment right off the bat.
Click to expand...

hiphish · Sep 26, 2021

Align panel as a package

I have decided to move the grid align panel into a separate package as well. There are a number of reasons for removing it from the core package:

The panel is not useful as a dependency for other scripts

It adds menu clutter to Unity for people who do not need it

I don't expect that many people to have use for it compared to the core

Installing a Git package is trivial

None of these points are particularly strong, but I cannot think of any downsides, so the decision was an easy one to make. In return I have added a sample to the package: a playground scene with some grids and objects you can move around and experiment with the different options. Such a sample would be pointless in the core, but it is appropriate for an external package.
Click to expand...

hiphish · Oct 11, 2021

Homestrech

It has taken more time than I had hoped, but Grid Framework version 3.0 is finally almost done. All the code has been written and tested, the logistics have been figured out, and the documentation has been updated. This has been quite and exciting year and it is good to see the goal ahead.

So what is still missing? For one, I had a really nasty data loss recently, and while I had everything important backed up, it is the many small and seemingly unimportant files that slow down the recovery process. I have all the small stuff sorted out, but the toughest nut to crack has ironically been Unity3D itself.

There are four different types of files on my computer:

Files I explicitly created myself

Files that belong to the system

Foreign files that are freely available

Foreign files under lock and seal

The first kind is easy enough, I created them willingly, I decide if they are worth backing up. The second kind is irrelevant, they will be replaced by the new system anyway. The third kind can be a bit of work, but since they are freely available it is usually just a matter of a simple download. The fourth kind is where it's at though: you have to jump through hoops to get them, and even when you have them you need to jump through even more hoops to get them to actually work. I have written about it in my main blog.

What is the solution here? Back up the proprietary files? That can be problematic if the backup gets stolen and the files leaked. The files might contain a unique identifier tied to you, so good luck proving that you did not leak them yourself. There is also no guarantee that the backed up files will work from a backup and won't want to re-authenticate, which brings us right back to the original issue. Honestly, I have no idea how to deal with this kind of problem, other than to just hope for the best. Or don't use proprietary software in the first place I guess.
Click to expand...

hiphish · Oct 30, 2021

Change of plans regarding Unity3D package

I have been very excited to be able to make use of the Unity3D package format for the major version 3 release because it solves a number of problems I had with the previous releases. Unfortunately I have to dial back somewhat because the Asset Store only accepts contents stored inside the Assets directory of a project.

Here is the new plan: the core of Grid Framework will be a regular Asset Store bundle while the align panel, Vectrosity support and Playmaker support still remain freely available Git packages. The core of Grid Framwork changes as follows:

Samples will be moved out of the core into another freely available Git package

The core will have its own assembly definition, this is necessary so that external packages can reference it

Documentation will be included with the core

I have decided to move the samples into a separate package in order to avoid bloat. In previous releases you would find all the textures, scripts, materials and shaders from the examples mixed in with your own assets. It is very annoying. If the Asset Store approval process rejects this, then I will have to include a minimal example with the least amount of bloat. The final choice is theirs.

As for the documentation, I consider online-only documentation to be unacceptable, so now I have the same problem as before: Unity will try to interpret the Javascript files as Unity Script, and it will treat images as textures. Fortunately I already solved this problem in the past through some fancy Unix hackery with ed and find:

Code (sh):

# Rename all JavaScript files to text files (prevents Unity from compiling them

# as UnityScript files)

for f in $(find manual/html -type f -name '*.js');

mv "$f" "$f.txt"

done

# Rename the PNG files or they will be mistaken for textures by Unity

for f in $(find manual/html -type f -name '*.png'); do

mv "$f" "$f.txt"

done

# Change the file extensions inside all HTML, CSS and JS files

for f in $(find manual/html -type f -name '*.html' -o -name '*.js.txt' -o -name '*.css'); do

printf ',s/([_a-zA-Z0-9]*)\\.js/\\1.js.txt/g\n,s/([_a-zA-Z0-9]*)\\.png/\\1.png.txt/g\nw\nq\n' \

| ed -s -E $f;

done

The last part is the most interesting one: I use printf to generate commands which I pipe into the ed text editor. The editor ed is driven completely through keyboard commands, there is no visual interface, which makes it perfect for automation. The final script is quite a hack, but it gets the job done.
Click to expand...

hiphish · Oct 31, 2021

Now we wait

Version 3.0 has been submitted to the Unity Asset Store team. It has been quite a wild ride, but now it looks like we are good to go. Now all that's left is to sit back, wait for a response and enjoy the calm. See you one the other side
Click to expand...

hiphish · Nov 10, 2021

Grid Framework version 3.0.0 released

Grid Framework version 3.0.0 has been approved by the Asset Store. This is a major release, it is not backwards compatible with version 2.x. Upgrading from version 2.x or 1.x is free for existing customers. Here are the highlights of this new major version:

Rendering backend API allows plugging in different backends for rendering grids

The old camera-based rendering is now a rendering backend

New mesh-based rendering backends

Separate assembly definition for Grid Framework

No more project bloat thanks to modular design: Grid Framework is now split into a core and additional sidegrade packages which can be installed as needed

Completely overhauled Playmaker bindings

Vectrosity support and Playmaker bindings are available as separate sidegrades

An upgrade guide is provided in the user manual.

The new rendering system
Previously there has been only one way to render a grid: by using the GL class and sending primitive rendering commands to a camera object. This worked reasonably well, but it had limitations and it would always draw lines on top of sprites.

Version 3.0 introduces an extra layer of abstraction between a grid renderer and the rendered output in the form of a message broker. Renderers were introduced in version 2.0 and allowed users to render a grid in many different shapes. In version 3.0 renderers send their result to a broker first, and the broker then forwards the data to one or more rendering backends. A backend is free to do anything with the data; it can draw lines to a camera using the GL class, it can generate a mesh with Lines topology and let Unity's rendering pipeline do the rest, it can forward the data to another framework such as Vectrosity, or it can just log the data to a file.

The following illustration is taken from the manual, it shows how the rendering system acts as a central hub between renderers and backends.

Code (CSharp):

+----------+

|renderer 1|-------+

+----------+ |

|

+----------+ | +-----------+

|renderer 2|-------+ +-------| backend 1 |

+----------+ | +--------+ | +-----------+

+-----| System |-----+

+----------+ | +--------+ | +-----------+

|renderer 3|-------+ +-------| backend 2 |

+----------+ | +-----------+

|

+----------+ |

|renderer 4|-------+

+----------+

A number of reasonable default backends (GL, mesh and Vectrosity) are already provided and users can define their own backends using the rendering system API. For details please consult the manual.

Modular design
In the past Grid Framework had been shipped as a monolithic package, which means that all its features were included. There was no other way of providing a complete package, but the method had a number of drawbacks:

Assets from examples would show up among the project assets

Activating support for 3rd party packages was cumbersome

It included a lot of code one might never need in a project

Providing examples for 3rd party packages was either cumbersome (Vectrosity) or impossible (Playmaker)

Grid Framework is now split up to be modular. This means there is one core package (which you purchase from the Asset Store) that provides a library containing everything you need. In addition there are now a number of sidegrades, optional packages you can install for non-essential features. These are:

Playable samples: playable examples to get started

Grid align panel: an editor extension for aligning and scaling objects in a scene

Playmaker support: Playmaker bindings for Grid Framework let you use grids in Playmaker's visual scripting

Vectrosity backend: a rendering backend using the popular Vectrosity library

These are all freely available as public Git repositories under the MIT license. You can add them easily to your project using Unity's package manager, which will track the packages.

Furthermore, this modular design allows other users to build and share their own 3rd party sidegrades. All sidegrades, whether official or not, have access to the same core API.

Overhauled Playmaker bindings
The new bindings consolidate related functionality into common actions. For example, instead of having a separate getter for each property for each grid, there is now one general getter per grid. Similarly, coordinate conversion is now only one action per grid with a dropdown to select the coordinate system instead of one separate action for each combination of coordinate systems.

Now that Playmaker bindings are provided as a Unity Git package I was also able to include playable examples.

Separate assembly definition
Grid Framework now resides in its own C# assembly instead of the main assembly. This makes it possible to use it as a dependency in packages.

Going forward
With the new rendering API I have been able to solve the last rough spot I could find. I expect that development of the core will slow down now, allowing the sidegrades to grow and experiment freely. Since the sidegrades are not tied to the core they can release independently and they can be forked into experimental packages without affecting the stability of the core.

I have plans to create a new rendering backed based on Linefy, a 3rd party line drawing 3rd party. Before the split this would have been awkward to work into the monolith, but not it's just another package.
Click to expand...

EvilNoodle · Jan 6, 2022

Hi,

I am trying to get this working with Vectrocity but I am just getting compile errors.

I have imported the latest versions of Vectrocity, the grid framework and the Vectrocity backend stuff from your git site by adding it as a dependency and importing through the unity package manager. I am now getting three build errors stating that the VectrocityBackend.cs file is unable to recognise the Vectrocity namespace which is true it can't.

I am currently using Unity 2021.2.7f1

Any ideas on how to solve this?

hiphish · Jan 7, 2022

EvilNoodle said: ↑

...
Click to expand...

Hello,

Does the included sample scene work for you? You can import it from your Unity Package Manager window, see the attached screenshot. If it does not there might be something wrong with how the Asset Store has packaged Grid Framework because it works on my machine. There should be a file in your Assets folder under com.hiphish.grid-framework/Runtime/ named com.hiphish.grid-framework.Runtime.asmdef with the following contents:

Code (csharp):

{

"name": "com.hiphish.grid-framework",

"rootNamespace": "GridFramework",

"references": [],

"includePlatforms": [],

"excludePlatforms": [],

"allowUnsafeCode": false,

"overrideReferences": false,

"precompiledReferences": [],

"autoReferenced": true,

"defineConstraints": [],

"versionDefines": [],

"noEngineReferences": false

}

Does this file exist on your machine?

EvilNoodle · Jan 7, 2022

Hi, Thanks for getting back to me.

The file you reference is present and contains the above. The sample projects appear OK although I am currently in a URP context which I don't think is supported so everything renders in pink.

I am trying to get the Vectrosity back end working to get around the aparant lack of URP support (unless I am missing something and there is some update script I need to run or something). The problem manifests when I import the Vectrosity backend from your git and I get the compiler issues so it feels to me like your backend project config doesn't know where to look for Vectrosity.

For reference the VectrosityBackend asmdef file looks like:

Code (CSharp):

{

"name": "com.hiphish.grid-framework.vectrosity.Runtime",

"rootNamespace": "GridFramework",

"references": [

"com.hiphish.grid-framework"

],

"includePlatforms": [],

"excludePlatforms": [],

"allowUnsafeCode": false,

"overrideReferences": false,

"precompiledReferences": [],

"autoReferenced": true,

"defineConstraints": [],

"versionDefines": [],

"noEngineReferences": false

}

Any thoughts?

Edit: Just to make sure there wasn't anything clouding the issues here I just created a brand new standard 3D project in 2021.2.7f1 using the inbuilt render pipeline, imported only Vectrosity, Grid Framework V3 and the Vectrosity backend in that order and it immediately gave the same issue.

Also just tried it in Unity 2020.3.25f1 to see if this was something to do specifically with 2021. Same issue.

I have been cloning your Vectrosity back end using the URL from the main branch (https://gitlab.com/HiPhish/grid-framework-vectrosity.git) as the one specified in your documentation (https://gitlab.com/hiphish/grid-framework-3-vectrosity.git#v3.0.0) appears invalid:

Code (CSharp):

[Package Manager Window] Cannot perform upm operation: Unable to add package [https://gitlab.com/hiphish/grid-framework-3-vectrosity.git#v3.0.0]:

Error when executing git command. remote: The project you were looking for could not be found or you don't have permission to view it.

fatal: repository 'https://gitlab.com/hiphish/grid-framework-3-vectrosity.git/' not found

[NotFound].

UnityEditor.EditorApplication:Internal_CallUpdateFunctions ()

hiphish · Jan 7, 2022

EvilNoodle said: ↑

...
Click to expand...

The assembly definition looks correct. Where have you imported Vectrosity? Mine is directly under Assets, the folder structure looks like this:

Code (csharp):

Vectrosity/

├── Plugins

│ ├── Editor

│ │ ├── VectrosityEditor.dll

│ │ └── VectrosityEditor.dll.meta

│ ├── Editor.meta

│ ├── Resources

│ │ ├── DefaultLine3D.mat

│ │ └── DefaultLine3D.mat.meta

│ ├── Resources.meta

│ ├── Vectrosity.dll

│ └── Vectrosity.dll.meta

└── Plugins.meta

EvilNoodle · Jan 7, 2022

Exactly the same place although Vectrosity no longer uses DLLs and has switched to a source only approach in the latest release (5.6.1 - October 2020 so not that new).

EvilNoodle · Jan 7, 2022

Yeah pretty sure that is the problem. I just did an experiment where I installed the three packages then manually moved the Vectrosity backend code into the main project (deleting its asmdf file) and then removed the package installed via git and that fixes the errors. The vectrosity sample scene kind of works (some things are broken as references are now invalid and I have no idea what used to be hooked in) but it does at least look like it compiles and runs (I can see the colourful Vectrosity grid) it looks like your package had a dependency on the DLL implementation in Vectrosity that is no longer valid since they stopped using DLLs.

Edit: Hooked in VectrosityBackend scripts as the missing components so all the demo elements work now. This is a workaround for the time being and gets everything functional again but it would be great if this just worked out of the box with the non-DLL Vectrosity version.

hiphish · Jan 8, 2022

EvilNoodle said: ↑

...
Click to expand...

Yes, that explains it. The problem is with how Unity compiles scripts into .NET assemblies. Packages live in a separate assembly and by default they only have access to the Unity standard library, but not your own scripts. For that you have to create your own assembly definition. Grid Framework has one (I created it specifically so that Grid Framework would work with packages), and when using the Vectrosity DLL no extra steps are needed. However, if you use the source version of Vectrosity, the Vectrosity code is indistinguishable from your own code for the compiler.

There are two solutions: one is to ask the author of Vectrosity if he can add an assembly definition. I am not aware of any downsides to doing so, but that doesn't mean there aren't any. The other solution is to add an assembly definition of your own, which is what I have done. Inside Assets/Plugins/Vectrosity/Scripts create an assembly definition (name does not matter, but I called mine "Vectrosity") with the following contents (or if you prefer the GUI set the fields to match the screenshot):

Code (csharp):

{

"name": "Vectrosity",

"rootNamespace": "Vectrosity",

"references": [],

"includePlatforms": [],

"excludePlatforms": [],

"allowUnsafeCode": false,

"overrideReferences": false,

"precompiledReferences": [],

"autoReferenced": true,

"defineConstraints": [],

"versionDefines": [],

"noEngineReferences": false

}

Next you need to instruct the Grid Framework Vectrosity backend package to use that assembly. Unfortunately Unity won't let you edit Git packages through the GUI, so you will have to edit the assembly definitions by hand. There is one inside the Runtime folder and one inside the Samples folder; double-click each one in the Unity editor to open them in your text editor and adjust the list to include your Vectrosity assembly definition, e.g.:

Code (csharp):

"references": [

"com.hiphish.grid-framework",

"com.hiphish.grid-framework.vectrosity.Runtime",

"Vectrosity"

],

Replace "Vectrosity" with whatever you have called your Vectrosity assembly definition.

I'm afraid this is as close to "out of the box" as I can make it for now. I could add the "Vectrosity" reference blindly, Unity does not seem to have an issue with non-existing references (I was able to build and run without issues on Linux), then users would only have to drop in the Vectrosity assembly definition. What do you think, is that an acceptable compromise?

Full_Tilt · Dec 28, 2022

Hiphish, thank you for producing your GridFramework. I've integrated and am using the mesh rendered, however I'm only seeing one slice on the display. This is true both in editor and run modes. Is there a setting that controls the viewing distance or expanse of the rendered grid? I'm in 3D with a grid on the XZ plane. I've attached an image showing the white grid from above, looking down on the XZ plane. I'd like the grid to be rendered "infinitely" across that plane, limited by some viewing distance. Thanks for any hints!

hiphish · Dec 28, 2022

Full_Tilt said: ↑

...
Click to expand...

Hello,

have you adjusted the rendering range of the grid? A grid is infinite in size, but we can only render a finite slice of it. The size of that slice is determined by the settings of the grid render component of the grid object. From your screenshot it looks like you are using the Rectangle render, so you need to adjust the LayerFrom and LayerTo properties of the render. There is no built-in way to adjust the value dynamically at runtime because there is no universally "correct" formula, so if you want to adjust the values dynamically you will have to use code for that.

Search Unity

Unity ID

Useful Searches

Grid Framework [scripting and editor plugins]

Attached Files:

Attached Files:

Attached Files:

Attached Files:

Attached Files: