Editor Gen Utils
Core utility library for the Building Architect Tool. Provides geometric math (line intersection, polygon operations, splines), array/string helpers, debug drawing, camera control, file I/O, and the s
Core utility library for the Building Architect Tool. Provides geometric math (line intersection, polygon operations, splines), array/string helpers, debug drawing, camera control, file I/O, and the shared output state used by all BAT modules.
Module Overview
| Aspect | Detail |
|---|---|
| File | extensions/editor/gen/utils.lua |
| Returns | U table |
| Requires | editor/gen/render |
| State | U.out - shared output/debug state for rendering, mode tracking |
Configuration Constants
| Field | Value | Description |
|---|---|---|
U._PRD | 1 | Production mode flag (0 = dev, 1 = prod) |
U._MODE | 'BAT' | Current tool mode (BAT, ter, conf) |
U._HERE | bool | true if local dev file inprod exists |
U.small_val | 0.00001 | Epsilon for floating point comparisons |
U.small_ang | 0.001 | Angle epsilon (radians) |
Public Functions - Geometry
| Function | Signature | Description |
|---|---|---|
U.lineCross | - | Alias for lineCross(a1,a2,b1,b2) → x,y intersection of two infinite lines |
U.line2line | (a1,a2,b1,b2) | Same as lineCross, returns vec3(x,y) |
U.lineHit | (src,tgt) | Line-to-segment intersection, returns point and parametric s |
U.segCross | (a,b,c,d) | Segment-segment intersection (both must cross) |
U.ray2seg | (a,b,c,d,sense) | Ray-to-segment intersection (directional) |
U.linePlaneHit | (line,aplane) | Closest ray-plane intersection distance |
U.circ2seg | (c,r,a,b,sence) | Circle-segment intersection points |
U.between | (a,b,list,sence) | Checks if all points in list lie between a and b |
U.onLine | (a,b,list,sence) | Checks if all points are collinear with segment a→b |
U.polyCross | (base,a,dir) | Finds polygon boundary crossings from point a in direction dir |
U.polyCut | (base,pfr,pto) | Splits polygon at two boundary points into two sub-polygons |
U.polyStraighten | (base,dbg) | Removes collinear/duplicate vertices from polygon |
U.polyCenter | (base) | Weighted centroid of polygon |
U.polyMargin | - | Insets/offsets polygon edges by margin |
U.inRC | (p, loops, ...) | Point-in-polygon test |
U.bounds | (set) | AABB min/max of point set |
U.density | (set) | Average nearest-neighbor distance |
U.toPoly | (p,base) | Projects point onto nearest polygon edge |
U.path2spline | (base) | Converts polyline to cubic spline with arc-length parameterization |
U.circSpline | (base) | Circular arc approximation through point triples |
U.curv | (a,b,c) | Curvature at point b |
Public Functions - Arrays & Strings
| Function | Signature | Description |
|---|---|---|
U.index | (list, p, prop) | Finds all indices of p in list (optional property match) |
U.map | (list, cb) | Maps function or property name over list |
U.pop | (list, e) | Removes first occurrence of e |
U.toggle | (arr, val) | Toggles value presence in array |
U.union | (a, b) | Set union of two arrays |
U.joint | (a, b) | Concatenates array b onto a |
U.mod | (ai, n) | Wraps index ai around range 1..n (or table length). Works with tables and numbers |
U.clone | (arr) | Shallow copy of array |
U.split | (s, d, plain) | Splits string by delimiter |
U.stamp | (list, plain, delim) | Sorted concatenation of list elements as string key |
U.v2stamp | (v, ndig) | Vector to rounded string key |
U.round | (val, ndig) | Round to ndig decimal places |
U.join | (arr) | Space-delimited string join |
Public Functions - I/O & Debug
| Function | Description |
|---|---|
U.lo(msg, yes) | Conditional debug logger (suppressed during drag, unless yes) |
U.dump(t, msg, lvl, lvlma) | Recursive table dump to console |
U.draw() | Renders all debug overlays from U.out.aset, U.out.atext, U.out.agraph |
U.toFile(obj, pth, fname, md) | Writes JSON to file (mode 'a' = append-if-unique) |
U.fromFile(fname) | Reads and decodes JSON file |
U.fromJSON(t) | Recursively converts {x,y,z} tables back to vec3 |
U.path2disk(path) | Creates directory path on disk, returns path string |
U.camSet(acoord) | Sets camera position and quaternion rotation |
U.inView() | Returns true if mouse is not over any ImGui window |
U.wait(ang) | Draws animated triangle indicator at camera forward |
U.shape2name(shapeName) | Extracts base name from DAE path |
Usage Example
local U = require('/lua/ge/extensions/editor/gen/utils')
-- Line intersection
local x, y = U.lineCross(a1, a2, b1, b2)
-- Polygon operations
local straightened, map = U.polyStraighten(polygon)
local center = U.polyCenter(polygon)
local inside = U.inRC(point, {polygon})
-- Debug output
U.dump(myTable, "Debug label:")
U.lo("Status: " .. tostring(value))Additional Module Fields
| Field | Type | Description |
|---|---|---|
U.small_dist | number | Distance epsilon (0.01) |
U.chop | function | chop(str, delimiter) - splits string by multi-char delimiter |
U._mode | string | Set to 'GEN' at module load |
U.less | function | less(a, b, v) - returns (a-b):dot(v) for directional ordering |
Additional Exported Functions
U.angDist(a, b)
Angular distance between two points as seen from camera.
a(vec3) - First pointb(vec3?) - Second point (defaults to mouse raycast hit)
Returns: number? - Angle in radians, or nil
U.angDistVert(a, b, sense)
Checks if mouse is near a vertical line segment between a and b.
a(vec3),b(vec3) - Segment endpointssense(number?) - Sensitivity threshold (default 0.015)
Returns: boolean? - true if mouse is near the segment
U.angDistSeg(line, b)
Angular distance from camera to closest point on line segment to point b.
line(table) -{vec3, vec3}segmentb(vec3) - Reference point
Returns: number? - Angle in radians
U.splineC(p, c1, c2, s)
Places point on blended circular arcs.
p(vec3),c1/c2(table) - Circle descriptors{c, r}s(number) - Blend parameter 0–1
Returns: vec3 - Interpolated point
U.spline2plane(apos, ap, adist)
Projects 3D points onto a spline's 2D parameter space.
apos(table) - Points to projectap(table) - Spline pointsadist(table) - Arc-length distances
Returns: table - Array of vec3(dist, z) in spline coordinates
U.polySpline(base)
Computes max curvature and direction vectors for a polyline.
base(table) - Polyline vertices
Returns: number, table - Max curvature, array of direction vectors
U.proj(p, dir)
Projects point onto plane perpendicular to dir through origin.
p(vec3),dir(vec3)
Returns: vec3
U.ray2plane(ray, p, norm)
Ray-plane intersection.
ray(table) -{pos, dir}p(vec3) - Point on planenorm(vec3) - Plane normal
Returns: vec3? - Hit point or nil
U.fileCopy(old_path, new_path)
Binary file copy.
Returns: boolean - true if file sizes match
U.forBackup(name)
Generates backup filename by inserting .s before extension.
Returns: string
U.forOrig(name)
Removes .s backup suffix from filename.
Returns: string
U.debugPoints(list, plus)
Offsets a list of points by plus vector.
Returns: table - Offset point array
U.boxMark(obj, out)
Marks scene object's bounding box corners in debug output.
Returns: vec3 - Center of bounding box
U.markUp(list, rma, clr, plus)
Draws debug spheres at positions scaled by camera distance.
U.proj2D(v)
Projects vec3 to XY plane (z=0).
Returns: vec3(v.x, v.y, 0)
U.push(arr, val, single)
Appends value to array. If single is true, only adds if not already present.
U.rand(a, b)
Random float in range [a, b].
Returns: number
U.perm(a)
Random permutation of array.
Returns: table
U.forStar(astem, ard)
Builds angle-sorted star of road branches from junction stems.
Returns: table - Sorted array of {rdi, fr, ndi, ang, v, next}
U.vang(u, v, signed, dbg)
Angle between two vectors. If signed, returns cross-product-signed angle.
Returns: number - Angle in radians (0 to π unsigned, -π to π signed)
U.line2seg(a, b, c, d, sense)
Infinite line (a,b) intersection with segment (c,d).
Returns: vec3?, number? - Intersection point and parametric s on segment, or nil
U.perp(v)
2D perpendicular: vec3(-v.y, v.x).
Returns: vec3
U.vturn(v, ang)
Rotates vec3 by angle in XY plane.
Returns: vec3
U.paraSpline(ap)
Fits parabolas through consecutive point triples.
Returns: table - Array of {a, b, c} parabola coefficients
U.rcPave(rc, aloop, mrc, apatch, istest)
Subdivides a rectangle with holes into triangulated mesh patches.
Returns: table, table, table, table, table - mbody, mhole, edges, paths, labels
U.rcWH(rc)
Width and height of a 4-vertex rectangle.
Returns: number, number
U.spline2(a, b, i, n)
Smooth interpolation between values a and b at position i/n.
Returns: number
U.toLine(p, line)
Distance from point to infinite line, plus projection point.
Returns: number, vec3 - Distance, projected point
U.onPlane(raypos, p, norm)
Projects a ray hit point onto a plane.
raypos(vec3) - Ray hit positionp(vec3) - Point on planenorm(vec3?) - Plane normal (default vec3(0,0,1))
Returns: vec3 - Point on plane along camera ray
U.draw()
Renders all debug overlays from U.out.aset, U.out.atext, U.out.agraph.
U.less(a, b, v)
Directional comparison: (a - b):dot(v).
Returns: number
See Also
- Gen Decal Editor - Related reference
- Gen Experimental Frame Editor - Related reference
- Gen Mesh Explorer - Related reference
- World Editor Guide - Guide
Editor Gen UI (Building Architect UI)
ImGui-based user interface for the Building Architect Tool (BAT). Provides the main editor windows for building shape selection, scope navigation, material/mesh picking, roof type selection, architect
Editor Gen World
Central world/scene management module for the Building Architect Tool (BAT). Manages the full lifecycle of procedural buildings: creation, editing, material assignment, forest item placement, DAE expo