# RuleEngineers v0.1.2 Alpha Getting Started

This document ships with the `v0.1.2 alpha` installer and is meant to help you
get productive quickly with the current build of RuleEngineers.

## What RuleEngineers Is

RuleEngineers is a native Windows editor for exploring multistate square-grid
cellular automata. It combines:

- a live pattern viewer on the left
- a rule editor on the right
- import and export tools for common CA workflows
- full-session save and load through `.rerule` files

## Main Workflow

The usual workflow in RuleEngineers is:

1. Create or select a pattern tab and edit `G0` or later generations.
2. Use the left-side pattern viewer to preview how the current rule behaves.
3. Step or run the simulation to inspect that behavior.
4. Save the session as a `.rerule` file.

Important idea:

- the rule starts out completely empty, so no cells are born or survive until
  you define behavior in the rule editor
- editing `G0` changes the starting pattern directly
- editing later generations changes the rule so that the previous generation
  evolves into the result you painted
- the left-side pattern viewer is best thought of as a live editable preview workspace
  for the current rule's dynamics

## Basic Controls

- `Enter`: play or pause the pattern viewer
- `Space`: step the pattern viewer forward
- `Backspace`: step the pattern viewer backward
- `R`: reset the pattern viewer
- `Ctrl+N`: create a new pattern tab in the rule editor
- `Ctrl+Shift+N`: copy the selected region from the pattern viewer into a new
  rule-editor pattern tab
- `Ctrl+S`: save the current session
- `Ctrl+O`: load a saved session
- `Ctrl+V`: import supported RLE text into the active pattern tab
- `Alt+I`: import a Golly `.rule` or `.table` file
- `Alt+R`: export the current rule as a Golly ruletable to the clipboard
- `Alt+E`: export Hensel notation to the clipboard when the rule is 2-state

Mouse behavior:

- right-drag paints cells
- `Shift` + right-drag cycles backward through cell states
- left-drag or middle-drag pans a surface
- mouse wheel zooms the surface under the cursor
- `Shift+LMB drag` selects a rectangular region in the pattern viewer

## Example Setup

If this is your first session, try this small setup:

1. Launch RuleEngineers.
2. Set the number of states to 2 or 3.  More states will make the rule more complex but allow more freedom.
3. Press `Ctrl+N` to create a pattern tab if one is not already available.
4. In the rule editor, paint a simple `G0` pattern, such as a tetromino or glider.
5. Try editing a later generation such as `G1` or `G2` and notice that the
   rule changes to satisfy that edit.
6. In the left panel, right-drag to paint a small seed pattern.
7. Press `Space` a few times to step the simulation and use the pattern viewer as
   a live preview of the rule you just defined.
8. Use `Shift+LMB drag` to select a pattern-viewer region if you want to copy it
   into a new rule-editor pattern tab.
9. Press `Ctrl+Shift+N` to create that new pattern tab from the selected source
   region.
10. Use `Ctrl+S` to save the session as a `.rerule` file.
11. If you are using 2 states, use `Alt+E` to export a Hensel rulestring, or use `Alt+R` to export a multistate ruletable.

That sequence gives you a quick feel for the two main work areas:

- the right side is where you define pattern generations and rule behavior
- the left side is a live preview workspace for the current rule

## Sessions and Sharing

- RuleEngineers saves full editor sessions as `.rerule` files.
- You can share your `.rerule` session files and exported rule data.
- Custom state colors are saved with the session.

## Usability Notes

- New tabs open unnamed, and you can rename them inline with `F2` or by
  double-clicking the tab name.
- Double-clicking a locked cell jumps to the transition that defines it, and
  the camera now centers on the target before the mouse moves.
- Locked-cell highlighting is a little easier to read, and red downstream
  markers make broken dependencies more visible after an upstream edit.

## Alpha Notes

This is an alpha build. Features, behavior, UI details, and file handling may
change as the project continues to stabilize.

If something feels surprising, save your session often and keep copies of
important `.rerule` files as you experiment.

If you have any questions or comments, feel free to contact support@r2intca.com.