Ergogen

Ergogen リファレンス

Ergogen — エルゴノミックキーボードの設計を YAML/JSON 設定から自動生成するツール。 Points / Outlines / Cases / PCBs を宣言的に記述し、SVG / DXF / JSCAD / KiCad 形式で出力する。 公式ドキュメント (docs.ergogen.xyz) 全 12 ページを構造化。

ディレクトリ構造

.claude/skills/ergogen/
├── SKILL.md                                ← このファイル（エントリーポイント）
└── references/
    ├── guide/README.md                     ← 利用ワークフロー索引（3 ページ）
    ├── config/README.md                    ← 設定構造・前処理索引（2 ページ）
    ├── sections/README.md                  ← 6 トップレベルセクション索引（6 ページ）
    └── formats/README.md                   ← 出力ファイル形式索引（1 ページ）

探索手順

1. ユーザーのタスクに最も関連するカテゴリを特定する 2. そのカテゴリの README.md を読む 3. README.md 内の一覧から必要な個別ファイルを選んで読む 4. 必要に応じて関連ページのリンクを辿る

カテゴリ → README.md マッピング

Config Overview

The heart of Ergogen is a single config file (YAML, JSON, or JavaScript). It is divided into six top-level sections that each handle a distinct phase of keyboard generation. Only points is required; all other sections are optional.

Signature / Usage

meta:
  # board metadata, author info, version requirements

units:
  # custom variables usable throughout the config

points:
  # key positions and layout coordinates (required)

outlines:
  # plate, case, and PCB outline generation

cases:
  # 3D-printable case objects via extrusion

pcbs:
  # KiCAD PCB template configuration

Options / Props

Notes

• YAML, JSON, and JavaScript config formats are all supported; the generator auto-detects the input type.
• points is the only required section — minimal configs can omit all others.
• units values defined here are available for use in every other section.
• For complex or repetitive configs, JavaScript-format configs allow branching, loops, and parametric functions.

Related

• Preprocessing

Preprocessing

Ergogen runs four sequential preprocessing steps on config files before interpreting them: unnesting, inheritance, parameterization, and skipping. String values that look like math expressions are also automatically evaluated.

Signature / Usage

# 1. Unnesting — dot-notation keys are expanded
nested.key.definition: value
# → { nested: { key: { definition: value } } }

# 2. Inheritance — $extends copies fields from another declaration
parent:
  a: 1
  b: 2
child:
  $extends: parent
  c: 3
# child → { a: 1, b: 2, c: 3 }

# 3. Parameterization — regex-based placeholder replacement
template:
  value: placeholder
  double_value: placeholder * 2
  $params: [placeholder]
  $args: [3]
# placeholder → 3, double_value → 6

# 4. Skipping — exclude intermediate declarations from output
abstract_base:
  a: p1
  b: p2
  $params: [p1, p2]
concrete:
  $extends: abstract_base
  $args: [10, 20]
  $skip: true   # not emitted as a real section

Options / Props

Notes

• Unnesting happens first; any object key containing a . is expanded into nested objects.
• Inheritance rules: undefined fields take the parent value; defined fields override; type mismatches favor the new value; arrays and objects merge recursively.
• $extends value must be the full absolute dot-notation path of the target declaration.
• Parameterization uses regex replacement, so placeholder names should be unique strings to avoid unintended substitutions.
• $skip: true is most useful for abstract intermediate declarations that are only meant to be inherited, not used directly.
• String values that are valid mathematical expressions (e.g., 3 * 2) are automatically evaluated to their numeric result.
• Unit variables defined in the units section are available as named variables inside math expressions throughout the config.

Related

• Config Overview

Config

File Formats

Ergogen accepts configuration input in multiple formats and produces output files for outlines, cases, PCBs, and visualization.

Input Formats

Output Formats

Notes

• PCB output is unrouted — no traces are placed. You must open the file in KiCad and route connections manually.
• PCB output does not include a KiCad schema (.kicad_sch) or project file (.kicad_pro); these must be created separately in KiCad if needed.
• Case output uses the JSCAD format, which can be opened and rendered at Cadhub or with a local OpenJSCAD installation.
• Input bundles (ZIP/EKB) allow packaging a config together with custom footprints for sharing or reuse.

Related

• PCBs
• Outlines
• Cases

Formats

Getting Started

Ergogen is a tool for designing ergonomic keyboards via YAML configuration files. It generates PCB layouts, case outlines, and related artifacts from a single config.

Recommended Workflow

1. Watch the introductory talk for a conceptual overview. 2. Read the documentation at ergogen.xyz. 3. Try the web-based interface (e.g., ergogen.cache.works) before installing the CLI. 4. Study real-world configs by searching the #ergogen topic on GitHub. 5. Ask questions on Discord if you get stuck.

Notes

• The CLI is optional — the web app is sufficient for initial exploration.
• Use the CLI only when you need unreleased features, custom modifications, or want to contribute code.
• Input files are written in YAML.

Related

• Usage
• Next Steps

Next Steps

After learning the basics, explore real-world configs and community resources to deepen your Ergogen knowledge.

Community Resources

Further Learning

• "Let's Design A Keyboard With Ergogen v4" — step-by-step tutorial series by FlatFootFox (flatfootfox.com)
• "The REAL Ergonomic Keyboard Endgame!" — video walkthrough by Ben Vallack (covers an earlier Ergogen iteration)
• Absolem blogpost — design case study at zealot.hu/absolem/

Notes

• Search the #ergogen GitHub topic to find and reverse-engineer real-world config files.
• Discord is the primary place for questions, contributions (examples, tests, features), and community discussion.

Related

• Getting Started
• Usage

Guide

Usage

Ergogen can be run through the official web app or the CLI. Both accept a YAML config and produce output artifacts (outlines, PCBs, cases).

Signature / Usage

Web App

Open https://ergogen.cache.works in a browser, paste or upload your YAML config, and preview the generated output directly — no installation required.

CLI (global install)

# Install (requires Node v14.4.0+ / npm v6.14.5+)
npm i -g ergogen

# Run
ergogen input.yaml -o output_folder

CLI (development build)

git clone https://github.com/ergogen/ergogen.git
cd ergogen
npm install
node src/cli.js input.yaml -o output_folder

Options / Props

For the full list of options run ergogen --help.

Notes

• The development build gives access to unreleased features not yet on npm.
• Output artifacts include point previews, outlines, PCBs, and cases depending on what is defined in the config.

Related

• Getting Started
• Next Steps

Cases

The cases section extrudes 2D outlines and composes them in 3D space to produce JSCAD solid geometry (.jscad output).

Signature / Usage

cases:
  top_plate:
    - what: outline
      name: board
      extrude: 1.5
  _wall:
    - what: outline
      name: board
      extrude: 12
    - what: outline
      name: board
      extrude: 11
      operation: subtract
  assembled:
    - what: case
      name: top_plate
    - what: case
      name: _wall
      shift: [0, 0, 1.5]

Options / Props

Notes

• Parts accept both array and object formats.
• Prefix a case name with _ to make it private (available for reference but not exported).
• Shorthand notation [+, -, ~] followed by a name is also accepted; Ergogen searches cases first, then outlines.
• Cases reference other cases by name, enabling layered 3D composition.
• Output is un-routed JSCAD solid geometry.

Related

• Outlines

Metadata

The meta top-level key stores keyboard documentation. Most fields are arbitrary strings, but Ergogen interprets three specific fields: engine, version, and author.

Signature / Usage

meta:
  engine: 4.0.6
  version: "1.0"
  author: your-name
  notes: any additional fields are ignored by Ergogen

Options / Props

Notes

• engine uses semver range semantics: 3.1.4 means "at least 3.1.4, up to (but excluding) 4.0.0".
• version and author differ from engine — they are plain strings passed through to KiCad output, not version constraints.
• Any other fields (e-mail, GitHub links, etc.) are accepted without error but have no effect on generation.

Related

• PCBs

Outlines

The outlines section builds 2D shapes by combining geometric primitives placed at key points. Each outline is assembled from an ordered list of parts; parts are combined via boolean operations.

Signature / Usage

outlines:
  _keycaps:
    - what: rectangle
      where: true
      bound: false
      size: [cx, cy]
  board:
    - what: rectangle
      where: true
      bound: true
      size: [cx, cy]
      expand: 2
      fillet: 1
    - what: circle
      where:
        ref: matrix_inner_top
      radius: 5
      operation: subtract

---

Shape Primitives

rectangle

circle

polygon

outline (reference)

---

Common Part Attributes

---

Operations

Parts are applied sequentially to build a cumulative shape:

---

Exports

• All named outlines are exported by default.
• Prefix a name with _ (e.g., _keycaps) to mark it as private — it can be referenced by other outlines but is not included in final output.

Notes

• bind/autobind values set on points control how far a rectangle extends to meet neighboring keys when bound: true.
• Parts accept both array and object formats.

Related

• Points
• Cases
• PCBs

PCBs

The pcbs section places footprints at key positions and assigns nets to produce un-routed KiCad PCB files (.kicad_pcb).

Signature / Usage

pcbs:
  main:
    outlines:
      edge:
        outline: board
        layer: Edge.Cuts
    footprints:
      keys:
        what: mx
        where: true
        params:
          net: "{{colrow}}"
    references: true
    template: default

---

Outlines

Defines PCB edge cuts and layer markings.

---

Footprints

Places components at filtered point locations.

Footprint Parameters

Parameters support {{key}} template syntax to access point attributes (e.g., {{colrow}}, {{name}}).

Provided parsed_params Fields (inside footprint body function)

Coordinate Helper Functions

Each returns an object with x, y, and str fields.

---

Top-Level PCB Options

---

Nets

Each unique net string is assigned a numeric index for KiCad.

Notes

• Generated .kicad_pcb files are un-routed; all pads and nets are defined but traces are not drawn.
• The template receives a parts object containing: names, version, author, nets, footprints, outlines, and custom params.
• version and author in the output come from the meta section.

Related

• Metadata
• Outlines
• Points

Points

The points section defines the 2D key positions [x, y, r°] that form the keyboard layout. It is built from zones (column/row grids) with optional post-layout adjustments (rotation, mirroring).

Signature / Usage

points:
  key:                        # global key defaults
    padding: u
  zones:
    matrix:
      anchor:
        shift: [0, 0]
      columns:
        outer:
          rows:
            bottom:
            top:
          key:
            stagger: 5
      rows:
        bottom:
        top:
      key:
        spread: u
  rotate: -10
  mirror:
    ref: matrix_outer_top
    distance: 250

---

Anchors

An anchor computes a 2D point [x, y, r°] relative to an existing point via translation and rotation.

Anchor Forms

Anchor Attributes

Anchor Example

anchor:
  aggregate.parts:
    - left_key
    - right_key
  shift: [1, 0]
  rotate: 180

---

Zones

Zones organize keys into column-staggered grids. Columns are processed left-to-right; rows bottom-to-top.

Zone Structure

points:
  zones:
    zone_name:
      anchor: <anchor>       # optional; default [0, 0, 0°]
      columns:
        col_name:
          rows:
            row_name: <key_attrs>
          key: <key_attrs>   # column-level defaults
      rows:
        row_name: <key_attrs>
      key: <key_attrs>       # zone-level defaults
  key: <key_attrs>           # global defaults

Inheritance Order (lowest → highest priority)

1. Built-in hardcoded defaults 2. Global points.key 3. Zone points.zones.<zone>.key 4. Column points.zones.<zone>.columns.<col>.key 5. Row points.zones.<zone>.rows.<row> 6. Key-specific points.zones.<zone>.columns.<col>.rows.<row>

Use the $unset directive to remove an inherited value.

Key-Level Attributes

---

Adjustments

Post-layout rotation and mirroring applied at zone or global scope.

Options

Mirroring and asym

Aliases for asym: origin/image, base/derived, primary/secondary, left/right.

Adjustment Example

points:
  zones:
    matrix:
      rotate: 10
      mirror:
        ref: matrix_inner_top
        distance: 200
  rotate: -5
  mirror: 100

Related

• Units
• Outlines

Sections

Units

The units section defines named numeric variables (usable as math formulas) throughout the rest of the config. Built-in units cover standard MX and Choc key spacings.

Signature / Usage

units:
  # override or extend built-in units
  a: cy - 7
  b: a * 1.5

Built-in Units

Internal Default Variables

These variables set default values for key-level attributes and can be overridden in units:

Notes

• Any string that is a valid math formula can be used as a unit value.
• Units can reference other units defined earlier in the same block.
• U (uppercase) and u (lowercase) are distinct: 19.05 vs 19.

Related

• Points