Getting Started

This guide walks you through creating your first CNC program with GScript, from writing code to generating machine-ready G-code.

Prerequisites

Before you begin, make sure you have:

• GScript installed
• A text editor (VS Code with GScript extension recommended)
• Basic understanding of CNC machining concepts

The GScript Workflow

GScript provides a complete toolchain for CNC programming:

Write GScript → Validate → Compile → Simulate → Generate G-code

Let's walk through each step!

Step 1: Write Your First Program

Create a new file called hello-cnc.gscript:

meta:
  part_name: "hello-cnc"
  material: "aluminum"
  units: mm

tooling:
  - id: mill-6mm
    type: endmill
    diameter: 6.0
    max_rpm: 12000

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

program:
  - op: face
    tool: mill-6mm
    depth: 1.0
    pass_depth: 0.5
    feed: 800
    bounds: rect(0, 0, 100, 80)

export:
  backend: grbl
  post_process: true

Understanding the Program

This simple program faces a 100mm x 80mm aluminum plate:

• meta: Defines part information and units
• tooling: Declares a 6mm endmill tool
• setup: Specifies stock dimensions and safe height
• program: Contains one face operation
• export: Configures G-code output for GRBL

Step 2: Validate Your Program

Before compiling, validate your GScript for errors:

gscriptc validate hello-cnc.gscript

This checks for:

• Syntax errors
• Invalid tool references
• Boundary violations
• Feed rate issues
• Type errors

Expected output:

✓ Validation passed
  No errors found

Step 3: Compile to G-code

Compile your GScript to machine-ready G-code:

gscriptc compile hello-cnc.gscript --target grbl -o output.gcode

Options:

• --target or -t: Backend target (grbl, marlin, fanuc, linuxcnc, tinyg)
• -o or --output: Output file path
• -O: Optimization level (0-3)

The generated G-code will be saved to output.gcode.

Step 4: Review the G-code

Open output.gcode to see the generated machine code:

; Part: hello-cnc
; Material: aluminum
; Generated by GScript

G21 ; Set units to millimeters
G90 ; Absolute positioning
G17 ; XY plane selection

; Tool: mill-6mm (6.0mm endmill)
M6 T1
S12000 M3 ; Spindle on at 12000 RPM
G0 Z5.0 ; Move to safe height

; Operation: face
G0 X0 Y0
G1 Z-0.5 F800
; [Toolpath continues...]

M5 ; Spindle off
G0 Z5.0 ; Retract
M30 ; Program end

Step 5: Simulate (Optional)

Visualize the toolpath before running on your machine:

gscriptc simulate hello-cnc.gscript

This provides:

• Toolpath preview
• Collision detection
• Material removal simulation
• Estimated cycle time

Step 6: Estimate Costs (Optional)

Calculate machining time and costs:

gscriptc estimate hello-cnc.gscript

Output includes:

• Total cycle time
• Rapid move time vs cutting time
• Tool usage statistics
• Material removal volume

Common Workflow Patterns

Pattern 1: Validate Before Compile

Always validate before compiling to catch errors early:

gscriptc validate my-program.gscript && gscriptc compile my-program.gscript --target grbl

Pattern 2: Multiple Backends

Generate G-code for different machines:

gscriptc compile program.gscript --target grbl -o grbl-output.gcode
gscriptc compile program.gscript --target fanuc -o fanuc-output.gcode

Pattern 3: Optimize for Production

Use higher optimization levels for production:

gscriptc compile program.gscript --target grbl -O3 -o optimized.gcode

Optimization levels:

• O0: No optimization (fastest compile)
• O1: Basic redundancy elimination
• O2: Feed rate optimization
• O3: Aggressive optimization (travel path, arc fitting)

Next Steps

Now that you understand the basics:

• Language Reference - Learn GScript syntax in detail
• Operations - Explore all operation types
• CLI Commands - Master the command-line tools
• Examples - Study real-world examples

Tips for Success

1. Start Simple

Begin with basic operations and gradually add complexity.

2. Use the Validator

Run validate frequently during development to catch errors early.

3. Leverage the LSP

If using VS Code, the GScript extension provides real-time validation and autocomplete.

4. Simulate Before Running

Always simulate complex programs before running on real hardware.

5. Keep a Library

Create reusable tool and material definitions that you can import across projects.

Getting Help

If you encounter issues:

• Check the Troubleshooting Guide
• Search GitHub Issues
• Ask in Discussions
• Review Examples for working code

Happy machining! 🔧