Interpreter development

When to use

The user wants to create an interpreter for a control system, add or fix NC words, adapt an interpreter to another machine or postprocessor, find out why a program is simulated wrongly, or prepare an interpreter for a customer.

This skill is the entry point of a set of skills. It has a general part that always applies, and five more skills to turn to as the work goes on:

Skill (folder)	Title used in cross-references	Turn to it for
`inspect-nc-programs`	"Inspect NC programs"	what the NC programs actually contain
`develop-dotnet-interpreter`	"Develop .NET interpreters"	the C# project, its files, the INI file, build and debugging — the default implementation
`develop-native-interpreter`	"Develop native interpreters"	native DLL projects (Delphi, C++ or another native language), the INCT ABI, the `.snci` file, Win64 builds (Win32 only for a 32-bit product), inheritance, protection and packaging — only when a native interpreter is needed
`nc-interpreter-foundations`	"How the kernel reads a block"	how the kernel reads a block and when your code runs
`verify-interpretation`	"Verify interpretation"	how to prove the change and what to hand over

Cross-references in these skills use the titles of the second column. Install all the skills together: they refer to each other.

Choose the implementation: .NET by default

Develop the interpreter in C# on .NET unless the user explicitly asks for something else. Use "Develop .NET interpreters" for every new interpreter and for every change to an interpreter that is already .NET.

Use the native implementation (Delphi, C++ or another native language, "Develop native interpreters") only when the user explicitly asks for a native interpreter, or when the work is on an interpreter that is already native. Do not propose a native implementation on your own. When the user does ask for one, everything needed is in "Develop native interpreters". The other way round holds as well: do not rewrite an existing native interpreter in .NET unless the user asks for it.

Who you are working with

Assume the user is a CNC specialist — a technologist, a support engineer, a tester — with basic programming skills. They know the machine and the control system far better than you do; they do not know compiler errors, git or software jargon. So:

explain each step in their terms: blocks, words, axes, cycles, the simulated toolpath;
keep the code plain: one handler per word, names a machine operator recognizes, a comment that says what a block does;
never ask them to type a command or a path you can find yourself;
when you need a decision, ask one short question and offer the options.

Establish the facts first

Before planning anything, know these six things. Ask for what is missing instead of assuming it.

The control system and its dialect — maker, model, version, the G-code system (for example A/B/C on a lathe control), and the programming manual of that control. The manual is the specification.
The machine — the CAM project with this machine (*.stcp), its axes and their addresses in the machine schema (X1, B1, Cs1…), its channels, spindles and turrets.
The starting interpreter — an existing interpreter for this or a similar control, or the template it will be created from. Say which, and whether it is a copy you may change. The interpreters shipped with the product implement only what the product's own postprocessors produce, and some of them only import a toolpath: they do not link NC lines to the toolpath and may simulate with offsets or doubled approaches. Check the purpose of a shipped interpreter in the documentation's list of interpreters before you start from it or use it as a parent.
The products — which CAM system and Tuner versions must load the interpreter, exactly as the customer has them installed. Each product version has its own .NET version and its own SDK package version (see "The SDK package and the product versions" in "Develop .NET interpreters").
The NC programs — real programs from this machine: generated by its postprocessor, written by hand, from other CAM systems. Get several, not one. The postprocessor that produces them is worth having too: it shows which variants of each word will appear.
The expected result — what the simulation must show for each program: the toolpath, the tool changes, the spindles, the cycles. A reference from the real machine or a trusted interpreter is best.

Then check what you actually have: the .NET SDK, the installed products, the CAM log folder, Visual Studio Code with the C# extension, and how the NC programs will be run through the interpreter — by a runner on the documented programming interface of the CAM system or by hand (see "Run the programs" in "Verify interpretation"). Report what is missing rather than substituting a guess.

Trust order for facts

What the actual NC programs contain, and what an actual run of the interpreter produced.
The programming manual of the control system — authoritative for what a word means.
The templates and the SDK package shipped with the installed product — authoritative for what the interpreter can call. Never use a member the released package does not contain.
The user's written decisions in the workspace — authoritative for their machines and conventions.
Existing interpreters for the same control (C# or Delphi) — evidence of how a word was handled, and of which kernel limits had to be worked around; not a specification and not a style guide.
General knowledge, only when marked as an assumption.

A word that looks familiar from another control is not the same word. M2=3 on one control is a spindle command, G33 with I and K has different meanings on different controls. Read the manual.

Do not implement a word from your memory of a manual. Find the manual first — in the customer's attachments, on the control maker's site, in the documentation shipped with the machine — and quote the page. An item left as an assumption is a task to resolve, not a footnote. When the behavior of the SDK helper matters, read its declarations and XML documentation in the released package and check the behavior on a short program instead of guessing.

Before estimating or implementing a cycle, look for it in every existing interpreter of the same control, in any language. Before removing someone else's workaround, reproduce the case it was made for: it may protect against a collision the code does not explain.

Words of the documentation

The product's documentation on interpreter development names some things differently from this skill:

Documentation	This skill
interpreter settings file	the `.snci` file
list of objects to interpret (`INCT_BlockExecArray`)	the execution queue, `Commands`
translation, interpretation	the read pass, the execute pass
former	toolpath former (`Create…Former`)
log of interaction with the interpreter	the CAM log with Use logs and Use log interaction with the interpreter on

Workflow

Restate the task as an observable difference in the simulation, and name the acceptance check: which program, which block, what must happen.
Take the census of "Inspect NC programs" on all programs you have: which words occur, in which spellings, and which of them the interpreter does not understand yet.
Find the place in the interpreter that handles each word ("How the kernel reads a block" explains where to look), and explain the current behavior before changing anything.
Decide what kind of change it is:
- a variation an INI key of this interpreter already covers — another axis name, a machine M function, a word without effect on the toolpath: change InterpreterSettings.ini, not the code. An interpreter fresh from a template has almost no such keys; adding the key is a code change once, and every later variation of the same kind is a setting;
- a new behavior — a cycle, a frame, a feed mode: change the code as "Develop .NET interpreters" describes (or "Develop native interpreters" when the interpreter is native, see "Choose the implementation: .NET by default"), and build the moves of a cycle with the kernel's toolpath formers ("Toolpath formers" in "How the kernel reads a block");
- a kernel or SDK limitation — the kernel does not offer what the word needs: say so, describe the workaround and its limits, and record what the product would have to change.
Make the smallest change, build it, run the programs again.
Follow "Verify interpretation": compare with the previous run on all programs, not only the one you fixed.
Report: what changed and why, the evidence, what is still not supported, and what the user must check.

Rules

Do not invent register names, kernel calls, SDK members or machine axis addresses. Read them.
Do not start a native interpreter unless the user explicitly asks for one or the interpreter is already native; the default is .NET. Do not rewrite a native interpreter in .NET unless the user asks for it.
Do not change the installed product, its templates or its DLLs, and do not ask the user to.
Do not turn an unknown word into silence. A word the interpreter does not simulate is either listed as "read without effect" (it does not change the toolpath in the simulation) or produces one warning per program.
Write warnings for the machine user, not for a developer: name the block or the word, what was not simulated and why, in the control's terms. A skipped cycle or motion goes through Kernel.Notify as well: an operation that calculates without it looks complete.
Simulate what the control would do with the program, not what the CAM operation intended. When the two disagree, report it as a postprocessor defect with the evidence; do not "fix" it in the interpreter.
Do not call a change done without a run on the real programs: a successful build proves only that it compiles.
Keep customer programs and projects out of the conversation where a reduced example will do, and never put license data, passwords or customer archives into it.
A package for a customer holds no names that do not belong to this customer — in file names, paths, settings, comments and README alike (see "Prepare the package" in "Verify interpretation").

The workspace

You have no memory between sessions; the workspace is it. Keep in the user's workspace, next to the interpreter: a short AGENTS.md with the machine, the control, the products and the rules of the work; the reference NC programs and their expected results; one short note per solved case in notes\. At the end of a task write down what was wrong, how it was found and what fixed it.

Keep a written list of every request and decision of the user in the workspace, and update it as the conversation goes on. Before you report a task as done, check it item by item with evidence — including the results of research you delegated: they are easy to receive and then forget to apply. A long conversation is summarized and details fall out of it; the list does not.

Done means

The change is minimal and explained, it is based on words read from the real programs and on the control's manual, the interpreter builds for every product version it targets, all programs were run and compared with the previous result, every word the interpreter does not simulate is named, and the checks left to the user — the simulation on the machine, the customer's acceptance — are stated explicitly.