4.1 Projects

A project is a folder. File > Open Folder… (Cmd+O / Ctrl+O) opens one, and File > Open Recent lists the folders opened before. The IDE reads every file below the folder, decides from each file name what kind of file it is, and groups the model files into contexts that are checked and run together.

4.1.1 Kinds of files#

The kind of a file follows from its name alone.

NameKindReference
*.kmetaDomain metamodel2.1 KMeta
EVENTS.kmeta, in any caseEvent metamodel2.1 KMeta
*.kmodelModel2.2 KModel
*.kstatesState machine2.3 KStates
*.frag.kstatesFragment, a page that container states of other state machines run2.3.12 Pages
*.kenv.jsonEnvironment descriptor4.1.2 Environment descriptors
*.kbridge.jsonBridge4.7 Bridges
*.vis next to a model fileLayout of a diagram, written by the IDE4.3 Diagrams
.karpfenprojectProject file4.1.6 The project file

An event metamodel can also have another name, such as lamp-events.kmeta, when a descriptor names it under events.

A fragment file holds one fragment, STATEMACHINE "name" FRAGMENT, and is named after it: the fragment bulb_test lives in bulb_test.frag.kstates. The language finds a fragment by its name alone, so the file name is a convention of the IDE that keeps the files easy to find. A fragment file whose name does not fit the name of its fragment, ignoring case, gets the warning fragment-file-name at that name, and so does a fragment file that holds a state machine that is no fragment. A fragment in a file named *.kstates is read and runs the same, without the warning.

The IDE leaves out these folders: .git, .gradle, build, out, .idea, .kotlin, node_modules, karpfen-runs and every folder whose name starts with a dot.

4.1.2 Environment descriptors#

An environment descriptor is a JSON file named *.kenv.json. It says which metamodel, event metamodel, model and state machines form one context, which object of the model each state machine is attached to, and how fast the model runs. A descriptor is what Run starts. The paths in it are relative to the folder of the descriptor and must lie inside the project.

4.1.2.1 Keys#

KeyValueMeaning
metamodelString, requiredThe domain metamodel, a .kmeta file.
eventsString or nullThe event metamodel, a .kmeta file. Without it the context has no events.
modelString, requiredThe model the runtime starts from, a .kmodel file.
stateMachinesList of objectsThe state machines. Each entry has file, a .kstates file, and attachedTo, the key of the object it runs on. The type of that object should be the type after ATTACHED TO in the state machine. An entry without attachedTo names an attachable state machine, which the environment keeps as a definition, see 4.1.2.3 Definitions, or a fragment, see 4.1.2.5 Fragments. Without the key the list is empty.
tickDelayMsNumberThe time in milliseconds between two ticks. Without the key it is 50.
eventTtlMsNumberHow long in milliseconds an event waits for a state machine that takes it. 0 keeps events until a state machine takes them. Without the key it is 3000.
observeObjectobjects, required, with "*" for every object, and domains, a list of event domains. A run does not use it, because the IDE observes the whole model and listens to every domain the state machines use.
runtimeObjectimage and pythonPackages. A run does not use it, because the IDE runs every model in its own container.
bridgesList of stringsBridge files. A run does not use it. The run dialog chooses the bridges, see 4.5 Running.

The editor reports these problems in a descriptor.

CodeSeverityCause
descriptor-missing-fileErrorA named file does not exist, lies in a left-out folder or lies outside the project.
descriptor-invalidErrorA named file is of the wrong kind for its key, a value is of the wrong kind, a required key is missing, or a key is written twice.
descriptor-unknown-keyWarningThe key is not one of the table above.
descriptor-state-machine-formError or warningAn entry with attachedTo names an attachable state machine or a fragment, or an entry without it names an attached one, an error. The same definition or fragment is listed twice, a warning.
deploy-observe-supersededInfoThe descriptor has observe.
deploy-hosting-ignoredInfoThe descriptor has runtime or bridges.
deploy-tick-delay-rangeErrortickDelayMs is below 0 or above 2147483647.
deploy-tick-delay-zeroWarningtickDelayMs is 0, so the runtime never waits between ticks.
deploy-event-ttl-never-expiresInfo or warningeventTtlMs is 0, an info, or negative, a warning. Events then never expire.

4.1.2.2 A minimal descriptor#

This descriptor runs the lamp with only its own state machine.

{
  "metamodel": "lamp.kmeta",
  "events": "lamp-events.kmeta",
  "model": "lamp.kmodel",
  "stateMachines": [
    { "file": "lamp.kstates", "attachedTo": "lamp" }
  ]
}

The descriptor of the example in examples/lamp also attaches switch.kstates to wallSwitch and sets the timing:

{
  "metamodel": "lamp.kmeta",
  "events": "lamp-events.kmeta",
  "model": "lamp.kmodel",
  "stateMachines": [
    { "file": "lamp.kstates", "attachedTo": "lamp" },
    { "file": "switch.kstates", "attachedTo": "wallSwitch" }
  ],
  "tickDelayMs": 500,
  "eventTtlMs": 5000
}

4.1.2.3 Definitions#

A state machine of the form STATEMACHINE "name" ATTACHABLE TO "Type", ... is attached to no object by the descriptor. Its entry has only file, and the environment keeps it under its name. The objects get instances of it through the behaves after of their type, an ATTACH clause or an EXCHANGE, see 2.3.11 State machine management and lifecycle.

The example in examples/spares attaches the room machine to the room and lists two definitions:

{
  "metamodel": "spares.kmeta",
  "events": "spares-events.kmeta",
  "model": "spares.kmodel",
  "stateMachines": [
    { "file": "room.kstates", "attachedTo": "room" },
    { "file": "glowing.kstates" },
    { "file": "flickering.kstates" }
  ],
  "tickDelayMs": 500,
  "eventTtlMs": 5000
}

The form of each file must fit its entry. The editor reports descriptor-state-machine-form at the file of an entry whose form does not fit.

A run uploads the definitions with the attached state machines, in the order of the descriptor, before it activates the environment. The runtime holds the definitions the descriptor lists and no others, so every name that a behaves after, an ATTACH or an EXCHANGE uses must be listed, see 4.5.4.7 State machine instances.

4.1.2.4 Creating a descriptor#

Right-click a folder in the Project tool window and choose New Environment File. A dialog asks for the name, and .kenv.json is added. The new descriptor names the files of the folder's current context: the metamodel, the events, the first model and every state machine. Each state machine is attached to the first object of its ATTACHED TO type, otherwise to the first object of the model, and otherwise to the placeholder "object". An attachable state machine and a fragment are listed without attachedTo. When the state machines use event domains, the descriptor also gets an observe key, which a run does not use. The timing keys are left out, so the defaults hold.

4.1.2.5 Fragments#

A fragment is listed like a definition, with file and without attachedTo. A context holds the fragments its descriptor lists and no others, and the container states of its state machines find their fragments among them. A fragment that a container state uses but the descriptor does not list is the error project.unknown-fragment at the name after USE, see 4.4 Validating.

The example in examples/pages composes the lamp from three fragments. The fragment bulb_test uses the fragment wiring_check in a container state of its own, and the state on of the lamp holds a container state that runs warm_up:

{
  "metamodel": "pages.kmeta",
  "events": "pages-events.kmeta",
  "model": "pages.kmodel",
  "stateMachines": [
    { "file": "lamp.kstates", "attachedTo": "lamp" },
    { "file": "bulb_test.frag.kstates" },
    { "file": "wiring_check.frag.kstates" },
    { "file": "warm_up.frag.kstates" }
  ],
  "tickDelayMs": 500,
  "eventTtlMs": 5000
}

4.1.3 Folders without a descriptor#

A folder without a descriptor forms a context of its own from the karpfen files directly inside it that no descriptor names. Its metamodel is the one .kmeta file that is not EVENTS.kmeta, its event metamodel is EVENTS.kmeta, and its models and state machines are all .kmodel and .kstates files of the folder, the .frag.kstates files included. An attachable state machine of the folder counts as a definition, a fragment of the folder is part of the context, and no state machine is attached to an object. Such a context is checked like any other, but it cannot be run, because Run needs a descriptor.

SituationFinding
Several .kmeta files other than EVENTS.kmetaThe info context-multiple-metamodels on each of them. The first in alphabetical order, ignoring case, is the metamodel. The others belong to no context.
No .kmeta file other than EVENTS.kmetaThe info context-no-metamodel on each model and state machine.

A folder that holds a descriptor forms no context of its own. Its karpfen files that no descriptor names belong to no context.

4.1.4 Files that belong to no context#

A file that belongs to no context is still checked. A state machine is read on its own, with the language features of the project, and its errors block a run like any other. A model or a metamodel is checked for its syntax only.

4.1.5 The project tree#

The Project tool window shows the folder in three sections, divided by lines.

  1. The project file .karpfenproject and the environment descriptors.
  2. The folder with the model files and their subfolders.
  3. The bridge files.

A double-click or Enter opens a file. A bridge file opens in its form. The .vis file of a diagram shows below its model file, which can then be expanded, and opens as text that cannot be edited.

The context menu of the tree has these entries.

EntryEffect
New KMeta File, New KModel File, New KStates File, New Fragment File, New Environment FileAsks for a name and creates the file in the folder of the entry, with the suffix added. A new file reads without errors in its context. A new fragment file gets .frag.kstates and holds a fragment named after the file, with an initial state, a final state and a transition between them.
Rename…Renames the file or folder. Not for the project folder itself.
Delete…Deletes the file or folder. Not for the project folder itself.
Reveal in Finder, Show in Explorer or Show in File ManagerShows the file in the file manager of the system.

Renaming a file does not change the descriptors or the other files that name it.

4.1.6 The project file#

The file .karpfenproject in the folder holds the settings of the project. The IDE writes it when one of its values changes, so a folder that was never changed has none. It is plain text with one key = value per line. A line that starts with # is a comment. The file can be edited by hand and kept in version control.

# karpfen project settings. karpfen IDE reads and rewrites this file.
theme = dark
zoom = 110
editorFontSize = 14
pane.runtime = shown 400
open = lamp.kstates
open = lamp.kmeta
active = lamp.kstates
bridge = http.kbridge.json
capture = on
feature.parallel = on
feature.trueParallel = on
KeyValue
themelight, dark or system.
zoomThe scale of the whole window in percent, from 70 to 200.
editorFontSizeThe font size of the editors, from 8 to 40. The default is 13.
pane.project, pane.outline, pane.problems, pane.output, pane.runtimeshown or hidden, then the size of the tool window. The default sizes are 260, 240, 200, 180 and 400. pane.output is the Language Tools Output. pane.runtime may end in detached when the Runtime tool window has a window of its own, see 4.5.4 The Runtime tool window.
openAn open file, relative to the folder. One line per tab, in the order of the tabs.
activeThe file of the active tab.
bridgeA bridge that was ticked in the last run dialog. One line per bridge.
captureon when Capture run to file was ticked in the last run dialog. Without the line it is off.
feature.<id>on for a language feature or a feature of the project that is switched on, see 4.1.7 Language features. Without the line the feature is off.

A value that makes no sense is dropped, and the default holds. A line with a key the IDE does not know is kept when the IDE writes the file.

4.1.7 Language features#

Five parts of the state machine language are optional. Each project switches them on by hand, and all are off in a new project.

FeatureId in .karpfenprojectReference
Historieshistory2.3.7 Histories
Tick limitstickLimit2.3.8 Tick limits
Breakpointsbreakpoints2.3.9 Breakpoints
Macrosmacros2.3.6 Macros
Splits and joinsparallel2.3.4.3 Splits and joins

Run > Language Features has one entry per feature. It says what a click does, such as Switch On Histories or Switch Off Histories. The IDE writes the change into .karpfenproject as a line such as feature.history = on, and an edit of that line by hand has the same effect.

While a feature is off, every use of it in a state machine is the error kstates.feature-off, and a run is blocked. Completion and the menus of the diagrams do not propose the feature. A run switches on the runtime features that the project needs: History for histories, TickLimit for tick limits and Breakpoint for breakpoints, see 3.2 Runtime features. With breakpoints on, a run has a debugger, see 4.6 Debugging.

Below the language features, the submenu has the features of the project. They are no part of the language: they change nothing in the texts, in the checks or in completion, and only switch a feature of the runtime on in every run.

FeatureId in .karpfenprojectNeedsEffect
Parallel branches on threadstrueParallelSplits and joinsEvery run switches on the runtime feature TrueParallel, which steps the branches of a split at the same time, each on a thread of its own, see 3.2.9 TrueParallel.

Its entry reads Switch On Parallel branches on threads or Switch Off Parallel branches on threads. While splits and joins are off, the entry is disabled. Switching splits and joins off switches it off as well, and a line feature.trueParallel = on in a project file without feature.parallel = on is dropped when the IDE reads the file. With the feature on, the order of the steps within one tick can differ from run to run, so leave it off when a run must repeat exactly.

4.1.8 Settings and logs outside the project#

Only the recent folders, the place and size of the window and the place and size of the detached Runtime tool window are kept outside the project, in ~/.karpfen-ide/settings.json. The log of the IDE is ~/.karpfen-ide/logs/ide.log, and the log of the language tools is ~/.karpfen-ide/logs/dsl-tools.log. The environment variable KARPFEN_IDE_HOME names another folder for both.

Source: this page on GitHub at commit 3b6029f, refreshed 16 November 2026. The whole reference as a PDF.