ProceduralToolkit

Procedural Toolkit 0.2.4-preview

Procedural Toolkit is a procedural generation library for the Unity game engine.

Warning: This is a programming toolkit, editor support is limited. | GitHub | Asset Store | Issues | Support email

Installation instructions

Requires Unity 2022.3 LTS or later. Tested on Windows, WebGL, Android and iOS.

There are several ways to install Procedural Toolkit:

Package Manager

The best way is to install this library as a Git package using the Package Manager. First, make sure that you to have Git installed and available in your system's PATH.

Then you can add the package using the link below, notice the upm branch at the end of the line:

https://github.com/Syomus/ProceduralToolkit.git#upm

If you don't want to use Git, you can download this library as an archive and install it as a local package.

Asset Store or .unitypackage

The other way is to import a package from the Asset Store or the Releases page. If you have any previous versions of the toolkit installed, it is highly recommended to delete them before importing a newer version.

Getting started

After installation you can import ProceduralToolkit namespace and start building your own PCG systems:

using UnityEngine;
using ProceduralToolkit;

public class ReadmeExample : MonoBehaviour
{
    private void Update()
    {
        Debug.Log(string.Format("<color=#{0}>{0}</color>", RandomE.colorHSV.ToHtmlStringRGB()));
    }
}

If you are using Assembly Definitions, you will also need to add ProceduralToolkit as a reference.

I have a problem with Procedural Toolkit

First, please search the open issues and closed issues to see if your issue hasn't already been reported. If it does exist, add a :thumbsup: to the issue to indicate this is also an issue for you, and add a comment if there is extra information you can contribute.

If you can't find a matching issue, open a new issue, choose the right template and provide us with enough information to investigate further. Alternatively, you can send a message to the support email.

Contributing

See CONTRIBUTING for a full guide on how you can help.

If you're looking for something to work on, check out the help wanted label.

If you just want to show your appreciation, you can send a donation through PayPal or Ko-fi.

Toolkit structure

Runtime/

• ArrayE: Various Array and List extensions, such as looped getters/setters and flood fills.
• CellularAutomaton: Generic cellular automaton for two-state rulesets. Common rulesets can be found in CellularAutomaton.Ruleset.
• ClipperUtility: Utility class for conversion of Clipper data from and to Unity format.
• ColorE: Color extensions, HTML colors, Gradient constructors.
• ColorHSV: Serializable representation of color in HSV model.
• CompoundMeshDraft: Helper class for mesh generation supporting large meshes and submeshes.
• DebugE: Collection of drawing methods similar to Debug.DrawLine.
• Directions: Enum with direction flags along three axes.
• Draw: Collection of generic vector drawing algorithms.
• DrawRaster: Collection of generic raster drawing algorithms.
• GizmosE: Collection of drawing methods similar to Gizmos.
• GLE: Collection of GL drawing methods similar to Gizmos.
• MeshDraft: Helper class for mesh generation.
• MeshDraftPrimitives: Constructors for MeshDraft primitives.
• MeshE: Mesh extensions.
• PathClipper and PathOffsetter: Clipper library wrappers.
• PTUtils: Various useful methods and constants.
• RandomE: Class for generating random data. Contains extensions for arrays and other collections.
• RendererProperties: Serializable Renderer properties, use Renderer.ApplyProperties extension to apply them to a target renderer.
• Tessellator: LibTessDotNet library wrapper.
• TextureE: Texture extensions.
• VectorE: Vector extensions.

Runtime/Buildings/

• BuildingGenerator: The main generation class. Generates buildings based on input configuration and strategies, reusable. See examples for details.
• ILayout, ILayoutElement, IConstructible, Layout, HorizontalLayout, VerticalLayout: Interfaces and classes used in facade layout generation.
• IFacadePlanner, IFacadeConstructor, IRoofPlanner, IRoofConstructor: Interfaces for strategies controlling the details of the building generation process.
• FacadePlanner, FacadeConstructor, RoofPlanner, RoofConstructor: Serializable wrappers for strategy interfaces.
• ProceduralRoofs: A collection of roof constructors for the building generator.

Runtime/Geometry/

See this wiki page for a matrix of available algorithms.

• Circle2, Circle3, Sphere, Line2, Line3, Segment2, Segment3: Representations of geometric primitives.
• Geometry: Utility class for computational geometry algorithms, contains various point samplers and helper methods.
• Closest2D, Closest3D: Collection of closest point(s) algorithms.
• Distance2D, Distance3D: Collection of distance calculation algorithms.
• Intersect2D, Intersect3D: Collection of intersection algorithms.
• IntersectionType: Enum used in intersection algorithms.
• Intersections folder: Structures containing information about intersections.

Runtime/Geometry/StraightSkeleton/

Classes used in straight skeleton generation.

• StraightSkeletonGenerator: A straight skeleton generator, computes a straight skeleton for the input polygon, reusable. The generation algorithm is loosely based on the work of Tom Kelly (2014) Unwritten procedural modeling with the straight skeleton.
• StraightSkeleton: A straight skeleton representation.
• Plan: Representation of the active plan during generation process.

Runtime/ClipperLib/

The Clipper library. Use PathClipper and PathOffsetter for seamless interoperability with Unity.

Runtime/LibTessDotNet/

The LibTessDotNet library. The recommended use is through the wrapper class Tessellator.

Runtime/FastNoiseLib/

The FastNoise library.

Shaders/

Depending on the installation type, the shader library can be used like this:

#include "Packages/com.syomus.proceduraltoolkit/Shaders/SDF.cginc"

Or like this:

#include "Assets/ProceduralToolkit/Shaders/SDF.cginc"

• Common.cginc: Collection of shaping and debug functions.
• Easing.cginc: Normalized easing functions.
• SDF.cginc: Collection of signed distance functions.
• Transitions.cginc: Collection of transition animations.
• Gradient Skybox: Simple gradient skybox.
• Debug folder: Debug shaders for some of the most common mesh channels.
• VertexColor folder: Textureless shaders for use with color information from the vertices.

Editor/

• ColorHSVDrawer: PropertyDrawer for ColorHSV.
• MeshFilterExtension: Mesh saving utility available at MeshFilter context menu > Save Mesh.
• ProceduralToolkitMenu: Submenu with constructors for primitives at GameObject > Procedural Toolkit.
• RulesetDrawer: PropertyDrawer for CellularAutomaton.Ruleset.

Tests/

Tests for the library

Samples

Buildings

A fully procedural building generator, creates an entire mesh from scratch and paints it's vertices. Keep in mind that the generated mesh has no uv map so using it with Standard shader is pointless.

• BuildingGeneratorComponent: A simple minimal example on how you can use BuildingGenerator
• BuildingGeneratorConfigurator: A configurator for BuildingGenerator with UI and editor controls.
• BuildingGeneratorReuse: An example on how you can reuse the same generator to generate multiple buildings.
• ProceduralFacadePlanner: A facade planning strategy, controls the layouts of the facades.
• ProceduralFacadeConstructor: A facade construction strategy, used in conjunction with ProceduralFacadePlanner.
• ProceduralRoofPlanner: A roof planning strategy, generates a roof description based on the input config.
• ProceduralRoofConstructor: A roof construction strategy, used in conjunction with ProceduralRoofPlanner.
• ProceduralFacadeElements: A collection of fully procedural facade panels for the building generator.
• PolygonAsset: A ScriptableObject container for vertices.
• BuildingGeneratorConfigurat