Your First Program

Let's write a complete GScript program from scratch. We'll create a simple drilling pattern - perfect for learning the basics.

What We'll Build

A program that drills four mounting holes in the corners of a 100mm x 80mm plate:

(10,70)  •─────────• (90,70)
         │         │
         │  Plate  │
         │         │
(10,10)  •─────────• (90,10)

Step 1: Create the File

Create a new file called mounting-holes.gscript in your text editor.

Step 2: Add Metadata

Start by describing your part:

meta:
  part_name: "mounting-holes"
  material: "aluminum-6061"
  units: mm

This tells GScript:

• The part is called "mounting-holes"
• You're machining aluminum
• All measurements are in millimeters

Step 3: Define Your Tool

Add a tool definition for a 5mm drill bit:

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

Breaking it down:

• id: drill-5mm - A name you'll use to reference this tool
• type: drill - It's a drill bit (not an endmill)
• diameter: 5.0 - 5mm diameter
• max_rpm: 5000 - Maximum spindle speed

Step 4: Configure Your Setup

Define your stock material:

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

This means:

• Stock is 100mm wide, 80mm deep, 10mm thick
• Tool retracts to 5mm above the stock for safe moves

Step 5: Add the Drilling Operation

Now for the actual machining operation:

program:
  - 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}

This operation:

• Uses the drill-5mm tool we defined
• Drills 8mm deep (through the 10mm stock)
• Uses a feed rate of 300 mm/min
• Drills at four corner locations

Step 6: Configure Export

Finally, specify your target CNC controller:

export:
  backend: grbl
  post_process: true

Complete Program

Here's the full program:

meta:
  part_name: "mounting-holes"
  material: "aluminum-6061"
  units: mm

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

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

program:
  - 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}

export:
  backend: grbl
  post_process: true

Compile Your Program

Now compile it to G-code:

gscriptc compile mounting-holes.gscript --target grbl -o mounting-holes.gcode

What Gets Generated

GScript generates clean, commented G-code:

; Part: mounting-holes
; Material: aluminum-6061
; Generated by GScript

G21 ; Set units to millimeters
G90 ; Absolute positioning

; Tool: drill-5mm (5.0mm drill)
M6 T1
S5000 M3 ; Spindle on at 5000 RPM

; Drill operation (4 holes)
G0 Z5.0 ; Safe height

; Hole 1: (10, 10)
G0 X10 Y10
G1 Z-8.0 F300
G0 Z5.0

; Hole 2: (90, 10)
G0 X90 Y10
G1 Z-8.0 F300
G0 Z5.0

; Hole 3: (10, 70)
G0 X10 Y70
G1 Z-8.0 F300
G0 Z5.0

; Hole 4: (90, 70)
G0 X90 Y70
G1 Z-8.0 F300
G0 Z5.0

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

Try Modifying It

Add More Holes

Want to add a center hole? Just add it to the locations:

locations:
  - {x:10, y:10, z:0}
  - {x:90, y:10, z:0}
  - {x:50, y:40, z:0}  # Center hole
  - {x:10, y:70, z:0}
  - {x:90, y:70, z:0}

Change the Depth

Make through-holes in thicker stock:

setup:
  stock: {x:100, y:80, z:20}  # Thicker stock

program:
  - op: drill
    depth: 18.0  # Drill deeper
    # ... rest of operation

Use a Different Tool

Switch to a larger drill bit:

tooling:
  - id: drill-8mm
    type: drill
    diameter: 8.0
    max_rpm: 4000

program:
  - op: drill
    tool: drill-8mm  # Reference the new tool
    # ... rest of operation

Common Mistakes to Avoid

Mistake 1: Tool ID Mismatch

# Wrong - tool ID doesn't match
tooling:
  - id: drill-5mm

program:
  - op: drill
    tool: drill-5  # Typo! Should be drill-5mm

GScript will catch this during validation:

Error: Tool 'drill-5' not found in tooling block

Mistake 2: Drilling Below Stock

# Wrong - drilling deeper than stock thickness
setup:
  stock: {x:100, y:80, z:10}

program:
  - op: drill
    depth: 15.0  # Deeper than 10mm stock!

GScript will warn you:

Warning: Drill depth (15.0mm) exceeds stock thickness (10.0mm)

Mistake 3: Locations Outside Stock

# Wrong - hole outside stock bounds
setup:
  stock: {x:100, y:80, z:10}

program:
  - op: drill
    locations:
      - {x:110, y:50, z:0}  # X is outside 100mm width!

GScript validation catches this:

Error: Drill location (110, 50) is outside stock bounds

Next Steps

Congratulations! You've written your first GScript program. Now try:

1. Add More Operations - Combine drilling with face or pocket operations
2. Explore Examples - Check out the examples gallery for more complex programs
3. Learn the Syntax - Read the language reference for all available features
4. Multiple Tools - Learn how to use multiple tools in one program

Pro Tips

Tip 1: Use Comments GScript supports YAML comments:

program:
  # Mounting holes for base plate
  - op: drill
    tool: drill-5mm
    depth: 8.0  # Through hole with clearance

Tip 2: Validate Early Run validation while developing:

gscriptc validate mounting-holes.gscript

Tip 3: Start with Safe Values When first testing:

• Use conservative feed rates
• Set safe_height higher (10mm instead of 5mm)
• Run a dry run on your machine first

Tip 4: Save Your Tools Create a tool library file you can reuse across projects (coming in future versions).

Happy drilling! 🔩