Language Reference

Complete syntax reference for the GScript language.

Program Structure

Every GScript program consists of five main blocks in YAML format:

meta:          # Part metadata
tooling:       # Tool definitions
setup:         # Stock and safety settings
program:       # Machining operations
export:        # Output configuration

All blocks are required (except comments).

---

Comments

GScript uses YAML-style comments:

# This is a comment
meta:
  part_name: "widget"  # Inline comment

Comments are preserved in generated G-code when possible.

---

Meta Block

Defines part information and global settings.

Syntax

meta:
  part_name: string     # Required
  material: string      # Optional
  units: mm|inch        # Optional (default: mm)
  origin: {x, y, z}     # Optional (default: {0, 0, 0})

Fields

Field	Type	Required	Description
part_name	string	✅	Descriptive name for your part
material	string	❌	Material being machined (for documentation)
units	mm or inch	❌	Units of measurement (default: mm)
origin	object	❌	Coordinate system origin (default: {x:0, y:0, z:0})

Examples

Minimal meta block:

meta:
  part_name: "mounting-plate"

Complete meta block:

meta:
  part_name: "widget-housing"
  material: "aluminum-6061"
  units: mm
  origin: {x:0, y:0, z:0}

Imperial units:

meta:
  part_name: "bracket"
  material: "steel"
  units: inch

---

Tooling Block

Defines all tools used in the program.

Syntax

tooling:
  - id: string            # Required, unique identifier
    type: tool_type       # Required
    diameter: number      # Required
    max_rpm: number       # Optional
    flutes: number        # Optional (endmills)
    length: number        # Optional

Tool Types

• endmill - End mill cutter
• drill - Drill bit
• face_mill - Face mill (large diameter)
• ball_nose - Ball nose end mill
• chamfer - Chamfer mill

Fields

Field	Type	Required	Description
id	string	✅	Unique identifier (referenced in operations)
type	string	✅	Tool type (see above)
diameter	number	✅	Tool diameter in specified units
max_rpm	number	❌	Maximum spindle speed
flutes	number	❌	Number of flutes (endmills only)
length	number	❌	Tool length

Examples

Simple drill:

tooling:
  - id: drill-5mm
    type: drill
    diameter: 5.0
    max_rpm: 5000

Multiple tools:

tooling:
  - id: face-mill
    type: endmill
    diameter: 12.0
    max_rpm: 8000
    flutes: 4

  - id: pocket-mill
    type: endmill
    diameter: 6.0
    max_rpm: 12000
    flutes: 2

  - id: drill-bit
    type: drill
    diameter: 4.0
    max_rpm: 5000

---

Setup Block

Defines stock material and safety parameters.

Syntax

setup:
  stock: {x, y, z}      # Required
  safe_height: number   # Required
  origin_offset: {x, y, z}  # Optional

Fields

Field	Type	Required	Description
stock	object	✅	Stock dimensions (width, depth, height)
safe_height	number	✅	Height above stock for rapid moves
origin_offset	object	❌	Additional origin offset

Examples

Basic setup:

setup:
  stock: {x:100, y:80, z:10}
  safe_height: 5

With origin offset:

setup:
  stock: {x:200, y:150, z:20}
  safe_height: 10
  origin_offset: {x:10, y:10, z:0}

---

Program Block

Defines the sequence of machining operations.

Syntax

program:
  - op: operation_type    # Required
    tool: tool_id         # Required
    # ... operation-specific parameters

Operation Types

GScript supports four main operation types:

1. face - Surface milling
2. drill - Point drilling
3. pocket - Rectangular pocket clearing
4. contour - Path following

---

Face Operation

Mill a flat surface over a rectangular area.

Syntax

- op: face
  tool: tool_id
  depth: number
  pass_depth: number
  feed: number
  bounds: rect(x, y, width, height)
  stepover: number  # Optional (default: 0.75)

Parameters

Parameter	Type	Required	Description
tool	string	✅	Tool ID from tooling block
depth	number	✅	Total depth to remove
pass_depth	number	✅	Depth per pass
feed	number	✅	Feed rate (mm/min or in/min)
bounds	rect	✅	Area to mill
stepover	number	❌	Stepover ratio (default: 0.75)

Example

- op: face
  tool: endmill-12mm
  depth: 2.0
  pass_depth: 0.5        # 4 passes total
  feed: 1200
  bounds: rect(0, 0, 100, 80)
  stepover: 0.75         # 75% of tool diameter

---

Drill Operation

Drill holes at specific locations.

Syntax

- op: drill
  tool: tool_id
  depth: number
  feed: number
  locations:
    - {x, y, z}
    - {x, y, z}
    # ... more locations
  peck_depth: number  # Optional

Parameters

Parameter	Type	Required	Description
tool	string	✅	Tool ID from tooling block
depth	number	✅	Hole depth
feed	number	✅	Feed rate
locations	array	✅	List of hole coordinates
peck_depth	number	❌	Peck drilling depth

Example

Simple drilling:

- op: drill
  tool: drill-5mm
  depth: 8.0
  feed: 300
  locations:
    - {x:10, y:10, z:0}
    - {x:90, y:10, z:0}
    - {x:10, y:70, z:0}
    - {x:90, y:70, z:0}

Peck drilling (for deep holes):

- op: drill
  tool: drill-8mm
  depth: 25.0
  feed: 200
  peck_depth: 5.0   # Retract every 5mm
  locations:
    - {x:50, y:50, z:0}

---

Pocket Operation

Clear material from a rectangular pocket.

Syntax

- op: pocket
  tool: tool_id
  depth: number
  pass_depth: number
  feed: number
  bounds: rect(x, y, width, height)
  strategy: climb|conventional|spiral  # Optional (default: climb)
  stepover: number  # Optional (default: 0.5)

Parameters

Parameter	Type	Required	Description
tool	string	✅	Tool ID from tooling block
depth	number	✅	Total pocket depth
pass_depth	number	✅	Depth per pass
feed	number	✅	Feed rate
bounds	rect	✅	Pocket boundaries
strategy	string	❌	Cutting strategy (default: climb)
stepover	number	❌	Stepover ratio (default: 0.5)

Strategies

• climb - Climb milling (recommended, better surface finish)
• conventional - Conventional milling (better for soft materials)
• spiral - Spiral pattern from outside to center

Example

- op: pocket
  tool: endmill-6mm
  depth: 5.0
  pass_depth: 1.5
  feed: 800
  bounds: rect(20, 20, 60, 40)  # Pocket at (20,20), size 60x40
  strategy: spiral
  stepover: 0.5  # 50% of tool diameter

---

Contour Operation

Follow a path for profile cutting.

Syntax

- op: contour
  tool: tool_id
  depth: number
  pass_depth: number
  feed: number
  path:
    - {x, y, z}               # Linear segment (3D)
    - {x, y}                  # Linear segment (2D, z=0 implied)
    - arc:{radius, end, clockwise}   # Arc segment
    - spline:{points, tension}       # Spline segment
    # ... more segments
  closed: boolean  # Optional (default: false)

Parameters

Parameter	Type	Required	Description
tool	string	✅	Tool ID from tooling block
depth	number	✅	Total cutting depth
pass_depth	number	✅	Depth per pass
feed	number	✅	Feed rate
path	array	✅	List of path segments (points, arcs, splines)
closed	boolean	❌	Close the path (default: false)

Path Segments

The path array supports three types of segments:

1. Linear Points (2D or 3D)

- {x:10, y:20}        # 2D point (z=0 implied)
- {x:10, y:20, z:0}   # 3D point

2. Arc Segments

- arc:{radius:10, end:{x:100, y:10}}                    # Counter-clockwise
- arc:{radius:10, end:{x:100, y:10}, clockwise:true}    # Clockwise

• radius: Arc radius in current units
• end: Arc endpoint (2D coordinates)
• clockwise: Optional, arc direction (default: false)

3. Spline Segments

- spline:{points:[{x:25, y:15}, {x:50, y:20}], tension:0.5}

• points: Array of 2D control points
• tension: Optional, curve tightness 0.0-1.0 (default: 0.5)

Note: No spaces after colons for YAML compatibility (e.g., {x:10, y:20} not {x: 10, y: 20}).

Examples

Open contour (linear):

- op: contour
  tool: endmill-4mm
  depth: 3.0
  pass_depth: 1.0
  feed: 600
  path:
    - {x:10, y:10, z:0}
    - {x:50, y:10, z:0}
    - {x:50, y:40, z:0}
    - {x:10, y:40, z:0}

Closed contour with rounded corners:

- op: contour
  tool: endmill-6mm
  depth: 3.0
  feed: 800
  closed: true
  path:
    - {x:10, y:0}
    - {x:90, y:0}
    - arc:{radius:10, end:{x:100, y:10}}
    - {x:100, y:70}
    - arc:{radius:10, end:{x:90, y:80}}
    - {x:10, y:80}
    - arc:{radius:10, end:{x:0, y:70}}
    - {x:0, y:10}
    - arc:{radius:10, end:{x:10, y:0}}

Organic shape with splines:

- op: contour
  tool: endmill-4mm
  depth: 5.0
  feed: 600
  path:
    - {x:0, y:0}
    - spline:{points:[{x:25, y:15}, {x:50, y:20}, {x:75, y:15}], tension:0.5}
    - {x:100, y:0}

---

Export Block

Configures G-code output generation.

Syntax

export:
  backend: backend_name       # Required
  profile: profile_name       # Optional
  optimization: O0|O1|O2|O3   # Optional (default: O1)
  post_process: boolean       # Optional (default: true)
  curve_tolerance: number     # Optional (default: 0.01)

Fields

Field	Type	Required	Description
backend	string	✅	Target CNC controller
profile	string	❌	Machine profile name
optimization	string	❌	Optimization level (default: O1)
post_process	boolean	❌	Enable post-processing (default: true)
curve_tolerance	number	❌	Curve linearization tolerance in mm (default: 0.01)

Backends

Backend	Description	Best For
grbl	GRBL controller	Hobby CNC routers, 3018/3040
marlin	Marlin firmware	3D printers with CNC mode
fanuc	Fanuc CNC	Industrial CNC machines
linuxcnc	LinuxCNC/EMC2	Open-source CNC control
tinyg	TinyG controller	Compact motion controllers
gcode	Generic G-code	Basic compatibility

Optimization Levels

• O0 - No optimization (debugging)
• O1 - Basic optimization (default)
• O2 - Standard optimization [planned]
• O3 - Aggressive optimization [planned]

Curve Tolerance

The curve_tolerance parameter controls the precision of curve linearization when splines or arcs need to be converted to line segments.

Range: 0.001 to 0.1 mm

Default: 0.01 mm (10 microns)

Impact:

• Lower values (e.g., 0.001-0.005): Higher precision, more line segments, larger G-code files
• Higher values (e.g., 0.02-0.1): Lower precision, fewer line segments, smaller G-code files

When to adjust:

• Tight tolerance (0.001 - 0.005): Fine details, finishing passes, small radius curves
• Standard tolerance (0.01): General purpose machining
• Loose tolerance (0.02 - 0.1): Roughing operations, large radius curves

Note: Native arc commands (G02/G03) are not affected by tolerance as they are passed directly to the machine controller. Tolerance only applies when curves must be linearized.

Examples

Basic export:

export:
  backend: grbl
  post_process: true

With profile and optimization:

export:
  backend: grbl
  profile: cnc-3018
  optimization: O1
  post_process: true

High-precision curves:

export:
  backend: grbl
  curve_tolerance: 0.005  # 5 microns for smooth curves
  post_process: true

---

Data Types

Numbers

diameter: 6.0
depth: 10
max_rpm: 12000

• Integers or floats
• No quotes needed
• Units determined by meta.units

Strings

part_name: "widget"
material: "aluminum"

• Quotes optional for simple strings
• Required if string contains special characters

Coordinates

origin: {x:0, y:0, z:0}
location: {x:10.5, y:20.3, z:0}

• Object with x, y, z fields
• All three coordinates required

Rectangles

bounds: rect(x, y, width, height)

• Function-style syntax
• Four numeric parameters
• Used for bounds in face and pocket operations

---

Validation Rules

GScript validates programs at compile time:

Required Fields

• All required block fields must be present
• Tool IDs must be unique
• Operation tool references must exist

Numeric Ranges

• Depths must be positive
• Feed rates must be positive
• Diameters must be positive
• Coordinates must be within stock bounds

Tool References

• Every operation must reference a defined tool
• Tool IDs are case-sensitive

Coordinate Bounds

• All coordinates checked against stock dimensions
• Safe height must be above stock top
• Depths cannot exceed stock thickness

---

Best Practices

Naming Conventions

Tool IDs: Use descriptive names

# Good
drill-5mm, endmill-6mm, face-mill-12mm

# Avoid
tool1, t1, d5

Part Names: Be descriptive

# Good
part_name: "bracket-left-v2"

# Avoid
part_name: "part1"

Organization

Keep operations in logical order:

program:
  # 1. Rough operations first
  - op: face
    # ...

  # 2. Pockets
  - op: pocket
    # ...

  # 3. Finishing operations
  - op: contour
    # ...

  # 4. Drilling last
  - op: drill
    # ...

Comments

Document your intent:

program:
  # Face top surface to establish reference plane
  - op: face
    tool: face-mill
    depth: 1.0
    # Remove minimal material for flat finish
    pass_depth: 0.25

Safety

Always set appropriate safe heights:

setup:
  safe_height: 5  # At least 2-3mm above highest feature

Use conservative feeds for new programs:

- op: face
  feed: 800  # Start slower, increase if comfortable

---

Next Steps

• Operations Guide - Detailed operation examples
• Tools Guide - Tool selection and configuration
• Examples - Complete working programs
• CLI Commands - Command-line reference