Core Concepts

Unity DOTS/ECS
It’s important to understand that Hewn Core is built with Unity DOTS. Hewn Core utilizes Unity’s data-oriented Entity Component System (ECS) to create, modify, and manage everything in Hewn Core. If you’ve only coded with traditional Game Objects and Mono scripts, don’t worry! You can use Game Objects and scripts in tandem with Hewn Core and/or write custom jobs to work alongside the Hewn Core job system.

Notable Components
When working with Hewn Core, you’ll mainly be working with Blocks, Block Components, Layers, Grid Positions, the Job Scheduler, and the World.

Grid Management

The grid is managed by a complex system that schedules jobs for adding, removing, and updating blocks, components, and other entities. Before you dive in, it’s important to understand the FGridPosition data structure, along with basic grid mathematics.

Coordinate Systems

Hewn Core supports both hex and square coordinate systems. Switching between coordinate systems is flexible and non-destructive. Positions are maintained for each coordinate system.

To switch between grid coordinate systems use
GWorldManager.World.SetGridType(newGridType);

Grid Scaling

Hewn Core supports nonuniform grid scaling, which allows you to change the size of your world’s grid cells.  When grid cells scale, the block components can scale as well, based on the chosen block component scaling behavior.

To scale block cells, use
GWorldManager.World.SetBlockScale(blockScale);
(note: square mode is currently set to (2, 1, 2) to work best with the samples).

To change the default block scale, use
GWorldManager.World.SetDefaultBlockScale(blockScale);

To change the block component scaling behavior, use
GWorldManager.World.SetBlockComponentScalingBehavior(scalingBehavior);

Currently, there are four block component scaling behaviors:
  1. Disabled: block components will not scale when the block scale changes.
  2. BlockScaleXZAverage: block components scale based on the average XZ value ratio of the current block scale and the default block scale.
  3. BlockScaleXZMin: block components scale based on the minimum XZ value ratio of the current block scale and the default block scale.
  4. BlockScaleXZMax: block components scale based on the maximum XZ ratio of the current block scale and the default block scale.

Block Management

Blocks exist as entities and are typically displayed as cubes or hexagonal prisms. See the Glossary for block properties.

Functions
To create a basic block data, use
 GBlockFactory.CreateNewBlock(gridPosition);

To add or update a block on the grid, use
GEntityUtilities.UpdateBlockEntity(blockData);

To get an existing block, use
GEntityUtilities.GetBlockEntity(gridPosition, out var blockData);

To remove a block, use
GEntityUtilities.DestroyBlockData(gridPosition);

Block Component Management

Block components exist as entities, layerable on blocks, and are typically represented as plants, rocks, and other environmental objects. However, how they’re visually represented is up to you! See the Glossary for block component properties.

Map Components
Block Components have a MapComponent (GMapComponentData) property. This struct contains important information that is used to load prefab entities at runtime and place them on the correct cell layer. 

See also the BlockComponents sample on how to configure custom map component prefab entities and load them at runtime.

Notes
  • Many block components can reside on one block. Each grid position has a Cell Layer, which indicates which layer within the cell a block component resides. 
  • There are four built-in block component “tiers” that correspond to a cell layer. 

Functions
To create a block component data using a map component data, use
GBlockComponentFactory.CreateBlockComponent(mapComponent, gridPosition);

To add or update a block component on the grid, use
GEntityUtilities.UpdateBlockComponent(blockComponent);

To get an existing block component, use
GEntityUtilities.GetBlockComponentData(gridPosition, out var blockComponentData);

To get all block components at a position, use
GEntityUtilities.GetBlockComponents(gridPosition, allocator);

If you have added custom tiers, use
GEntityUtilities.GetBlockComponentsGeneralized(gridPosition, allocator);

To remove a block, use
GEntityUtilities.RemoveBlockComponentData(gridPosition);

Layers

Layers are planes that group blocks and block components. Layers allow you to separate, hide, and organize areas of blocks. See the Glossary for layer properties.

To create a layer, use
GLayerFactory.CreateLayer(id);

To add or update a layer on the grid, use
GLayerUtilities.AddOrUpdateLayer(layer);

To remove a layer (and all blocks and components on it) use
GLayerUtilities.DestroyLayer(layer);

Voxel Mode

In voxel mode, the W of each grid position is used to index vertically.  We don’t use the Y value for vertical position because that’s reserved for hex-space positions.

For a basic voxel setup, use
GWorldManager.World.SetupVoxelMode(gridTypeCode);

Notes
  • Layers can still be used when in voxel mode.

Mathematics

  • See GGridCoordinates for methods for grid position math.
  • See GGridNeighbors for methods for finding neighbors and ranges.
  • See GWorldCoordinates for methods for world-space conversions.