How to Create Custom Shapes with nfsGeometryCube

nfsGeometryCube: Quick Guide to Setup and ParametersnfsGeometryCube is a compact, versatile geometry utility used in procedural modeling and 3D engine pipelines for generating cube-based primitives with extended parameterization. This guide explains installations, core concepts, detailed parameter descriptions, common workflows, examples, and troubleshooting tips to help you integrate nfsGeometryCube into your projects quickly.

---

What is nfsGeometryCube?

nfsGeometryCube creates cube primitives that can be customized beyond a simple box: per-face subdivisions, non-uniform scaling, face-specific materials/UVs, edge chamfers, and procedural deformation hooks. It often appears as a module/plugin in 3D authoring tools or as a library in rendering/physics engines, letting artists and developers generate optimized cube meshes programmatically.

---

Installation & Integration

• If nfsGeometryCube is distributed as a plugin: install it using your host application’s plugin manager or by copying the plugin package into the application’s extensions folder, then restart the app.
• If it’s a library (npm, pip, etc.): install via the package manager. Example (replace with actual package name as needed):
  • npm: npm install nfs-geometry-cube
  • pip: pip install nfsGeometryCube
• For engines without package managers, add the source file to your project and include/import it where needed.

After installation, confirm availability by creating a new cube primitive via the host UI or by instantiating the cube class in code.

---

Core Concepts

• Anchor point: the cube’s origin/ pivot; can be centered or aligned to a face or edge.
• Dimensions: width, height, depth — controls the cube’s size on each axis.
• Segments/subdivisions: per-axis subdivisions that determine vertex density.
• Face attributes: per-face UVs, materials, visibility toggles.
• Edge chamfer/bevel: softens edges by adding geometry around corners.
• Deformation hooks: callbacks or modifiers for procedural tweaks (noise, taper, bend).
• Export options: generate smooth/flat normals, tangent space, and LOD-friendly topology.

---

Parameters — Detailed Reference

Below are common parameters found in nfsGeometryCube implementations. Names may vary slightly across versions; consult your version’s docs for exact names.

• width (float)

  • What it does: sets the cube size along the X axis.
  • Typical range: >0. Default: 1.

• height (float)

  • What it does: sets the cube size along the Y axis.
  • Typical range: >0. Default: 1.

• depth (float)

  • What it does: sets the cube size along the Z axis.
  • Typical range: >0. Default: 1.

• segmentsX / widthSegments (int)

  • What it does: number of subdivisions across the width.
  • Use for tessellation, deformation, and correct shading.
  • Typical range: 1–64. Default: 1.

• segmentsY / heightSegments (int)

  • Similar to segmentsX but along the Y axis.

• segmentsZ / depthSegments (int)

  • Similar to segmentsX but along the Z axis.

• pivot / anchor (enum or vector)

  • Options: center, bottom, top, custom vector.
  • Affects placement and transformations.

• faceVisibility (array[6] of bool)

  • Toggle visibility per face (useful for hollow structures).

• faceMaterialIndices (array[6] of int)

  • Assign a material index to each face for multi-material meshes.

• faceUVs (array[6] of rect or mapping])

• chamfer / bevel (float)

  • What it does: radius of the edge bevel; 0 = sharp edges.
  • Adds geometry; increases vertex/triangle count.

• chamferSegments (int)

  • Number of segments used to approximate the bevel curve.

• smoothingGroups / flatShading (bool)

  • Choose between flat or smooth shading per face or entire mesh.

• generateNormals (bool)

  • Toggle auto-generation of normals.

• generateTangents (bool)

  • Useful when using normal maps.

• twoSided (bool)

  • Make faces double-sided (duplicate vertices with inverted normals).

• deformationCallback (function)

  • A hook to apply per-vertex modifications (noise, twist, taper).
  • Typical signature: fn(vertices, uvs, normals, params).

• lodLevels (int or array)

  • Precompute multiple LODs for performance in real-time engines.

• vertexColor (bool or array)

  • Support for per-vertex color data.

---

Common Workflows

1. Quick primitive
   • Instantiate with default dimensions (1,1,1), set materials, export.
2. High-detail sculpt base
   • Increase segments to 32+ per axis, export to sculpting tool (ZBrush, Blender).
3. Game-ready asset
   • Use segments = 1 (or minimal), apply chamfer = small value, generate tangents, export as FBX with multiple material slots.
4. Procedural variation
   • Use deformationCallback to apply per-vertex noise and random per-instance parameters to create a library of variations.
5. Hollow container
   • Disable one or more faces with faceVisibility, flip normals for inside-out rendering if needed.

---

Code Examples

Example pseudocode for creating a basic cube and applying a chamfer and UVs:

import { nfsGeometryCube } from 'nfs-geometry-cube'; const cube = new nfsGeometryCube({   width: 2,   height: 1,   depth: 1.5,   segmentsX: 2,   segmentsY: 2,   segmentsZ: 2,   chamfer: 0.05,   chamferSegments: 3,   pivot: 'center',   generateTangents: true }); cube.applyFaceMaterials([0,1,1,0,2,2]); scene.add(cube.mesh); 

Example deformation callback (pseudo):

cube.deformationCallback = function(vertices, uvs, normals, params){   for (let i=0;i<vertices.length;i++){     const v = vertices[i];     const noise = snoise(v.x*1.5, v.y*1.5, v.z*1.5);     v.x += noise * 0.02;     v.y += noise * 0.02;   }   return {vertices, uvs, normals}; }; 

---

Performance Considerations

• More segments + chamfers = more triangles. Keep segments low for real-time use.
• Prefer normal maps for surface detail instead of heavy subdivision when targeting games.
• Use LODs for distant objects; generate simplified meshes by reducing segments and removing bevels.
• Bake vertex colors or ambient occlusion into textures for runtime efficiency.

---

UV Mapping Tips

• For simple boxes, use a 6-face unwrap layout: each face occupies a portion of the UV square.
• For pixel-perfect texture alignment, set consistent texel density across faces.
• When using atlases, assign faceMaterialIndices to map multiple materials onto a single mesh and lay out UVs to avoid overlap.
• For mirrored or tiled faces, manually adjust UV scale/offset per-face.

---

Troubleshooting

• Visible seams: check UV seams and normals; re-generate normals or split vertex normals per face for crisp edges.
• Unexpectedly high polycount: disable chamfer or reduce chamferSegments; lower segment counts.
• Normal map artifacts: ensure tangents are generated and UVs are non-overlapping.
• Flipped normals/culling issues: check face winding order and twoSided parameter, flip normals if necessary.

---

Frequently Asked Questions

• Can I create non-cubic rectangular prisms?
  • Yes — set width, height, and depth independently.
• Can faces have different materials?
  • Yes — use faceMaterialIndices or assign materials per-face in your exporter.
• Is there support for exporting to FBX/GLTF?
  • Most implementations provide exporters or you can convert the mesh in your host application.

---

Example Use Cases

• Level-blocking: fast, parameterized blocks for game prototyping.
• Asset pipelines: base mesh generator for modular kitbash parts.
• Procedural cities: generate building blocks with varied dimensions and chamfers.
• Baking workflows: create high-detail cube variants for normal map baking.

---

Final Notes

nfsGeometryCube is straightforward in concept but powerful in practice when its parameters are used together: combine subdivisions for deformation, chamfers for shading fidelity, and per-face controls for UV/material workflows. Start with conservative defaults and iterate: small changes to segments or chamfer can dramatically affect polycount and shading.

---