ConstructCraft

The interface: ribbon, commands and palette

Versão em português: interface.pt-BR.md.

ConstructCraft’s window follows the layout desktop CAD and BIM users expect. The quick access toolbar sits at the top left. Below it is the ribbon, a row of tabs with groups of buttons. The options bar for the active tool comes next. The project browser and properties are docked on the left, the views fill the tabs in the middle, and the status bar is at the bottom. When many views are open, Close Inactive Views (in the quick access toolbar and in View → Windows) closes every tab but the active one, and right-clicking a tab offers Close Other Views.

Commands and their tooltips

Every button in the ribbon and the quick access toolbar runs an interface command. So does every two-letter shortcut and every entry of the command palette. Each command defines, in one place:

• its name and icon;
• its shortcut: a Ctrl chord, or two letters typed while a view has the focus;
• a description of what it does;
• the engine command that makes the change. Scripts, the ccad command line and the MCP server call this same command (see the automation guide);
• whether it can run now, and why not.

Hover over a button to see its tooltip:

Move  [MV]
Moves the selected elements from a base point to a target.
Unavailable: Select the elements before using the tool
Engine command: elements_move

Buttons that cannot run are greyed out, and their tooltip gives the reason. Typical reasons are “nothing to undo”, “select the elements first”, “open a sheet to export it”, “select one text note” and “copy elements first”. A shortcut typed when its command cannot run shows the same reason in the status bar.

Icons and badges

Icons are drawn in two tones: the strokes in the text color and the soft fills in the theme’s accent tint. A small badge in the bottom-right corner marks what kind of action a command is:

Badge	Meaning	Examples
green +	creates something new	new floor or ceiling plan, 3D view, legend, drafting view, schedule, sheet, new component
blue arrow down	brings data in from a file	Import IFC, Import CAD, Load component
blue arrow up	writes data out to a file	Export PDF, Export SVG, Export Image, Export DXF
red −	removes something	Delete

The selected tool is highlighted in the accent color. Unavailable commands are greyed out, badges included.

Collapsing the ribbon

To give the views more room, collapse the ribbon to its tab titles. Any of these collapses it or expands it again:

• Ctrl+F1;
• a double click on any tab;
• the arrow at the right end of the tab row.

While the ribbon is collapsed, a click on a tab shows that tab’s panel over the views. The panel closes when a command runs, when you press Esc or click elsewhere, or when you click the same tab again. Whether the ribbon starts collapsed is set in Preferences → Interface.

Narrow windows

When the window is narrower than a tab’s groups, the groups scroll sideways instead of being cut off. Arrows appear at both ends of the row: click them to scroll, or use the mouse wheel. Each arrow is greyed out once that end is reached.

Command palette

Ctrl+Shift+P opens the command palette, as does the magnifier at the right end of the tab row. Type part of what you are looking for. The search ignores case and accents (“niveis” finds “Níveis”), and every word you type must match. The palette finds:

• interface commands, by name, description or shortcut (typing WA finds Wall);
• plans to create for each level (“Floor plan: Ground floor”) and schedules for each category;
• views to open (“Open view: …”);
• engine commands (level_create, elements_list, type_set…), shown in a monospaced font.

Use ↑ and ↓ to choose and Enter to run, or click an entry. Esc closes the palette. An unavailable command stays in the list, greyed out, with its reason in place of the description.

Running engine commands

Choosing an engine command opens a form with its description and its arguments in JSON, already filled with the required fields:

{
  "elevation": 9.0,
  "name": "Roof deck"
}

Run (or Ctrl+Enter) executes the command in the open project and shows its result or error message. An edit is one undo step and is recorded while a macro is recording, like any other change. Back (or Esc) returns to the search. The arguments are the same as in scripts and in the command reference. Lengths are in meters, angles in degrees, points are [x, y], and levels, types, views and materials can be named by id or by name.

The engine’s file commands (project_open, project_save, ifc_import, ifc_export, sheet_export, view_export…) are not offered here. Their interface commands in the File and Insert tabs and the palette handle files through the usual dialogs.

Keyboard

Key	Action
Ctrl+Shift+P	Command palette
Ctrl+F1	Collapse / expand the ribbon
Ctrl+,	Preferences
Ctrl+N / Ctrl+O / Ctrl+S / Ctrl+Shift+S / Ctrl+W	New / Open / Save / Save as / Close project
Ctrl+Z / Ctrl+Y	Undo / Redo
Ctrl+X / Ctrl+C / Ctrl+V	Cut / Copy / Paste
Delete	Delete the selection
Esc	Cancel the operation, leave the tool, clear the selection
Backspace	While drawing a chain of walls, beams, pipes or conduits: take back the last segment and go on from its start (Ctrl+Z too; Ctrl+Y puts it back); a railing’s last point
Space	Rotate or flip the selection or the element being placed

Two-letter keys work while a view has the focus and no text field is being edited. The README lists them all. Each tooltip shows its own shortcut as well.

Selecting in 2D views

A click picks the element under the pointer (Ctrl adds or removes it). A drag that starts on empty paper, or inside a floor, a hatch or another fill, draws a selection box: dragged to the right it is a window and takes the elements wholly inside it (their lines, fills and texts); dragged to the left it is a crossing, dashed and green, and also takes those it cuts or lies in: a wall crossed between its ends, a floor around the box, a text anchored in it. Room areas and imported drawings are not taken by a crossing (a window around them takes them). Ctrl keeps the current selection and adds to it. A drag that starts on an element’s line, or on an element already selected, moves it instead (Ctrl+drag copies).

Tags of doors, windows, beams, columns and footings can be dragged to another spot with the Select tool (the pointer turns into a hand over them). The tag keeps its text and gets a leader back to its element; each plan keeps its own tag positions (a duplicated plan starts with those of the original). Reset Tag, in the element’s properties, puts it back where it sits by default.

Annotate → Levels places level marks. Level in Plan (in a floor or ceiling plan) draws a circle with two filled quarters on the clicked point and writes the finished level of the floor under it above a shelf line and the raw level of its structure (the top of the layers below its finish) under it; off any floor it writes the plan’s level. Level in Section (in a section or elevation) draws a triangle pointing down to the point and writes its height, with the raw level when the point lies on the top of a cut floor; in a section the tool snaps to the view’s lines, so a click on a floor’s top line lands on it. The values follow the model; in the properties palette a mark can set either level by hand, hide the raw one or put the values on the left. The type holds the text size, the datum (the value written for the project’s zero, e.g. 100.00) and the suffixes, (N.A.) and (N.O.) by default in Portuguese.

Editing several elements

With several elements of one category selected, the properties palette shows their Type and Level (Base Constraint for walls, columns, stairs, ramps and shafts) and the parameters they share: the walls’ Location Line, the base offset, the Top Constraint (unconnected, or up to a level; walls made unconnected keep their height) with its offset or the Unconnected Height, sill height, overhang, rotation, Structural, Room Bounding, the walls’ joins at their ends, flips, and the identity data (Mark and Comments). A value that differs among them shows ‹varies› (an indeterminate box for on/off ones); choosing or typing one sets it on all of them in one undo step (the command elements_set; types through elements_set_type). A mixed selection shows how many of each category and Delete.

Selecting in 3D views

With the Select tool, a click picks the element under the pointer (Ctrl adds or removes it). Shift+drag draws a selection box, as in plans: dragged to the right it is a window and takes the elements wholly inside it; dragged to the left it is a crossing and also takes those it touches. Elements behind others count too; hidden ones do not. Ctrl keeps the current selection and adds to it. With Dragging in 3D views selects on in Preferences → Interface, a plain left drag draws the box and Shift+drag orbits instead.

Modifying in 3D views

Move, Copy, Array, Rotate, Mirror (pick or draw the axis), Align and Join Geometry/Unjoin Geometry also work in 3D views; left-drag still orbits (or Shift+drag, see above), middle or right drag pans.

• Points are picked on a horizontal working plane at the level of the elements being changed; once the first point is picked, the next ones stay at its height. A square marks a snap to a model point near the pointer: a corner of an element, the center of a column or component at its base or top, a wall end, a grid crossing. A cross marks a point on the plane. Shift keeps the main axis; a typed distance and Enter work as in plans. The preview shows the elements’ outline where they will go.
• Every change is a plan transform: elements keep their level. Moving a level 2 column from one of its corners to the matching corner of the column below puts it over that column.
• Align (AL, also in plans): click the face or line to align to, then the face or line of the element to move. While you point, the face or line a click would take is drawn thick; once the reference is chosen it shows as a red dashed line across the view, until the second click or Esc. The element moves in plan, so the two may be on different levels (a column above onto the face of the column below). Every element aligns by the face or side nearest to the click (a wall by either face, a column by a side); grids, and elements picked from the command line without a point, by their location line. When the two are not parallel, the element first turns about the point clicked until they are.
• Attach Top (Modify → Geometry): with walls selected, click a roof, ceiling or floor in a plan, elevation or section. Under it each wall rises or drops to its underside, following its slope (a gable wall ends in a triangle up to the ridge); where it is not under it, a wall keeps its own top, and a wall straddling its edge counts as under it. The walls follow the roof when it changes, and keep their own top again if it is deleted. Detach Top, or the button under Top attached to in a wall’s properties, gives them back their own top. Arc walls keep their own top. wall_attach does the same from the command line.
• Trim/Extend to Corner, Trim/Extend to Reference, Split Element, Offset and Allow/Disallow Join pick ends and sides on plan linework and stay unavailable in 3D views, with that reason in their tooltip.

View graphics

View → Graphics holds Visibility/Graphics (VG), Filters and View Templates (also under Manage).

• Visibility/Graphics edits the active view (or, from the template manager, a template). The Model Categories and Annotation Categories tabs list each category with a visibility box and cells for projection lines, surface fill, cut lines, cut fill, halftone and transparency; a cell shows the override (— when none) and opens an editor with color, weight (paper mm) and pattern. The Filters tab lists the filters applied to the view, in priority order (↑ ↓), with enabled and visible boxes and the same cells; Add Filter… applies another one and Edit Filters… opens the filter editor. When the view’s template controls categories or filters, the tab says so and is read-only. OK keeps the changes, Cancel undoes them.
• Filters edits the project’s filters: name, categories (none: all) and rules — a parameter, an operator and a value — combined with AND or OR, with the number of elements matching.
• View Templates lists the templates; Create from View makes one from the active view. Each property has an Include box; Apply Properties copies the template into the active view once, Assign to View makes the view follow it. The view’s properties show its template (choose None to free it) and a Visibility/Graphics button; properties the template controls are read-only.
• Detail level (Coarse, Medium, Fine), in the Graphics section of a plan’s, elevation’s, section’s or 3D view’s properties, and a template property: at Coarse, layered walls, floors and roofs are cut as one plain region (no layer lines, no material patterns); at Medium (the default) and Fine they show their layers. Each component piece has Shown at boxes for the three levels (all checked by default), so a component can draw a simple block in coarse views and its details only in fine ones; doors and windows too.
• Visual style, in the Graphics section of every plan’s, elevation’s, section’s and 3D view’s properties, and a template property (View default leaves each view its usual style): Wireframe draws every edge, seen through the model, with no faces; Hidden line fills faces in white so they hide what is behind them; Shaded fills them in their material’s color, lit from the viewer’s side; Consistent colors in the material’s color, the same on every side; Textures in the material’s appearance color with its surface pattern (Surface Pattern in the material browser: brick, concrete, sand, hatches…) at real size in 3D views and at the view’s scale in 2D views. Plans are drawn in hidden line by default; in the colored styles the faces below the cut plane (above it, in ceiling plans) are filled under the plan’s linework, and the wireframe drops fills and hatches. Elevations, sections and 3D views are shaded by default. view_set and template_set take visual_style.
• Underlay, a section of every floor and ceiling plan’s properties and a template property: the plan of another level drawn halftone under the view’s own, for reference while drawing. Plan below and Plan above take the next level below (or above) the view’s, which suits templates, or a given level; Seen from draws it looking down, as a floor plan, or up, as a ceiling plan. Only the model is shown (no annotations), in the faint pen and with the view’s category visibility; it is not picked, selected or snapped to. It is shown on screen only, unless Print underlay puts it on sheets and in exports. view_set and template_set take underlay (e.g. {"below": {"level": "Next", "looking": "Down"}}); deleting a level drops it from the underlays that name it.
• Section marks in plans follow NBR 6492 (figure A.19): at each end a 12 mm circle with the drawing’s number over the sheet’s (while the section is on no sheet, the last word of its name over a dash), on a filled triangle pointing where the section looks, joined by an extra-wide dash-dot line. Click a mark to select it (its properties show the section’s), drag it to move it, drag its square handles to move an end, press Space to flip it, and Delete to delete the section. Split line in its properties draws only a piece of line next to each head; drag the round handles at the pieces’ inner ends to bring them closer to their head (or set Segment at start/end). view_set takes start, end and segments ([at start, at end] in meters, or null).
• With elements selected, Override Graphics changes their graphics in the active view only and Hide in View (EH) hides them there (shown again from Visibility/Graphics).
• Hide/Isolate (temporary): HH hides the selection, HI isolates it, HC and IC hide or isolate its categories, HR resets. While active, the view has a colored border and a chip with Reset and Make Permanent. Temporary hiding is not saved, not undone and not printed.

Sketching outlines

Floors, ceilings, roofs, foundation slabs and masses are sketched in a plan. Their tool opens a sketch: the ribbon shows Create Boundary with the drawing tools until Finish or Cancel.

• Draw: lines (chained until the loop closes; Chain in the options bar), rectangles, inscribed and circumscribed polygons (Sides in the options bar), circles, ellipses, arcs by three points, by their center, and tangent arcs that continue the free end of a line or arc. Points snap to the model and to the sketch’s own ends, middles and centers. Pick walls adds lines along the walls of the level. After the first point, type a value and press Enter: a line’s length (Tab switches to its angle), a rectangle’s width and, after Tab, its depth, a circle’s or polygon’s radius, the distance of Move and Copy; the value runs towards the cursor, Backspace edits it and Esc drops it.
• Select: a click picks a curve (Ctrl adds or removes), a double click the chain of curves joined to it, a window the curves inside it (dragged to the left, those it touches); its grips stretch it (an end drags the ends joined to it, so loops stay closed; an arc’s middle grip changes its bulge, a circle’s and an ellipse’s grips their radii). The properties palette shows the picked curve’s start, end, center, radius, semi-axes and rotation, to type them. Delete removes the picked curves; Ctrl+Z and Ctrl+Y undo and redo the sketch’s own changes.
• Modify: Move, Copy (Multiple places copies from the same base point), Rotate (center, reference and final direction, or a typed angle and Apply) and Mirror (across a line of the sketch, or an axis drawn with two points; Copy keeps the originals) act on the picked curves. Offset copies the curve under the cursor Distance away on the side clicked; with Chain the whole chain of joined curves is copied, neighbors meeting where their copies cross (ellipses have no offset). Trim/Extend to Corner makes two curves meet, keeping the parts clicked; Trim/Extend to Reference takes a reference curve, then trims or extends each curve clicked to it; lines run on along their line, arcs round their circle. Split Element cuts a curve in two where it is clicked (a circle or a whole ellipse into halves, which can then be trimmed). The two-letter shortcuts of these tools work in the sketch too.
• Finish makes the element. Loops inside the outline become openings of floors and roofs. A sketch that is open, branches or crosses itself stays open, with the place marked and the reason in the status bar.
• Edit Boundary (Modify → Sketch) opens the sketch of the selected floor, ceiling, roof or mass: its curves as drawn, or lines along its outline. Moving, rotating and mirroring the element keeps its curves; editing its points directly drops them.

Roof coverings and framing

A roof type sets its covering and its framing, in the type dialog’s Covering and Framing section.

• Covering: ceramic tiles (colonial, French, Roman, Portuguese), concrete tiles, corrugated fiber cement, trapezoidal metal sheets or sandwich panels. Each comes with reference figures: the least slope it takes, its weight per m², tiles per m², the batten gauge and the widest span between purlins. They are typical values from public product data, for early design; the manufacturer’s prevail.
• Framing: Timber puts battens right under the roof at the tile’s gauge, rafters down the slope under them (at the rafter spacing) and purlins along the eaves under the rafters, spread evenly from eave to ridge no farther apart than the purlin spacing (or the covering’s span, when smaller). Timber trusses adds trusses under the purlins, across the ridge and no farther apart than the truss spacing: top chords along the roof faces, a level tie, a king post under the apex and struts to the middle of each chord. Steel puts purlins only, right under the sheets. Sizes, spacings and material are set on the type. Choosing a covering picks the framing it usually lies on, if none was chosen.
• The framing follows the roof’s sloped faces, whatever its shape, and shows in 3D views, elevations and sections in its material. It is not part of the roof’s own volume. IFC export writes each member as an IfcMember in the roof, and importing that file brings the covering and framing back on the roof’s type.
• A roof’s properties show the covering, its slope against the covering’s least (in red when below), the number of tiles, the weight and the framing’s lengths and volume. Roof schedules can list Slope, Tiles, Weight, Framing Length and Framing Volume. The roof_check command returns the same, with the rules the roof breaks.

Conceptual masses

Massing & Site → Massing → Mass (MS) sketches an outline in a plan, like a floor, and extrudes it up to the level above. Masses are for massing studies before walls and floors exist: see-through bodies in 3D views, elevations and sections, cut in the plans they cross.

• Properties: the base offset and the height, and whether the mass is an extrusion or a loft (a top outline different from the base, made with mass_create and top or top_inset).
• Mass floors: one box per level the mass spans, with the area of the floor at that level. Plans draw the floor of their level with its area; the properties and the Masses schedule give the gross floor area (the sum of the floors), the number of floors and the volume.
• Push/Pull (Massing → Push/Pull, PP, in a 3D view): click a face of a mass, then move the pointer along the arrow (or type the distance) and click or press Enter. The top changes the height, the bottom moves down or up, and a side of an extrusion moves out or in, the sides beside it keeping their directions (a loft’s sides stay; push its top or bottom). A mass with a floor at every level it spans gets the floors of the levels it reaches. Esc lets go of the face.
• From the mass to the building: with masses selected, Massing → Walls by Face puts a wall on each side of an extrusion (exterior face on the mass’s face, as tall as the mass, joined at the corners), Floors from Mass Floors a floor on each mass floor (the mass’s outline at that level, its top at the level) and Roof by Face a flat roof on the top. The walls, floors and roof are ordinary elements: change their types, heights and shapes as usual. A loft’s slanted sides take no walls.
• Moving, rotating, mirroring, copying and pasting work as for other elements. Deleting a level removes its mass floors. IFC export leaves masses out.

Terrain

Massing & Site → Site → Terrain (TS) sketches the terrain’s boundary in a plan, like a floor’s outline, and places its measured points: Points → Point clicks a point at the elevation set in the options bar (above the level), and undo takes points back like curves. Finish triangulates the points with the boundary; the boundary takes the elevations the points give it, points beyond it included, and the earth closes down to a flat base. A project without a terrain type gets one, cut in an Earth material (a woven hatch).

• Plans draw the terrain of their level: contour lines below the cut plane (every fifth a heavier major one) and, where the cut plane crosses the surface, the earth above it hatched and outlined as cut. Elevations, sections and 3D views show the solid, and sections cut the earth in its material.
• Properties: the base depth, the lowest and highest elevations, the area and volume (also in Terrain schedules), any warning (too few points, points on one line, a boundary that crosses itself), and the points themselves, whose x, y and z are edited in place or removed. Edit Boundary reopens the sketch with its points to change the boundary or add points. The type sets the material, the contour interval and how often a major contour comes.
• IFC export writes an IfcGeographicElement (TERRAIN); importing that file brings the terrain back with its points.

Massing & Site → Site → Building Pad (PD) sketches a pad’s outline on the terrain of the plan’s level, at the Elevation of the options bar; without a terrain there the button says so. Finish grades the terrain: flat inside the outline, a cut slope where the ground stands above the pad and a fill slope where it lies below, out to where they meet the existing ground (the daylight line).

• Plans draw the pad’s outline with its elevation, ticks across its slopes (long and short in turn, the short ones from the top of the slope), the daylight line, and the existing ground’s contour lines dashed where the pad changed it. Sections cut the graded earth and dash the existing ground line.
• Properties: the elevation, the cut and fill slopes (By type, or the pad’s own ratio, shown as 1:n), the area, the cut and fill volumes and the net, any warning (the slopes reach past the terrain), and Edit Boundary. The type sets the two ratios. Pad schedules list the elevation, area and volumes, with totals.
• The pad moves and is deleted with its terrain. IFC export keeps its pads in the terrain’s ConstructCAD_Pads property set, which import reads back.

Railings and their hosts

Curtain walls are walls of a curtain type (a project without one gets one from the wall tool’s type list: + Curtain Wall). Their type properties set the vertical and horizontal grids (layout, spacing or number, justification), the panel (glass, solid, empty, or a door, window or other component) and the vertical, horizontal and border mullions. Architecture → Build → Curtain Grid edits one wall’s grid by clicking it in a plan, elevation or section: Add Line (vertical or horizontal; plans add vertical ones), Remove Line (the nearest), Merge/Split Segment (the piece of a line between two others: the cells on both sides become one panel, or two again) and Swap Panel (the panel chosen in the options bar, or the type’s again); hovering shows what a click does. A selected curtain wall’s properties show its cells, panel count, glazed area and mullion length, and Reset puts back the type’s lines or panels.

Architecture → Circulation → Railing (RA) draws a railing along the points you click, at its level plus the base offset. A railing can also follow a stair or ramp (its host): it runs along the host’s side at the pitch of the nosings or of the slope, turns at its landings, and moves, changes and is deleted with it.

• On a stair or ramp: tick On a stair or ramp in the railing tool’s options bar, then click a stair or ramp in a plan. The railing goes on the side nearest the click, or on both with Both sides. A stair’s or ramp’s properties also have Add railings for both sides at once.
• Side and host: a hosted railing’s properties show its host and its Side (walking up), which can be switched. Detach from Host makes it an ordinary railing that keeps the path it has in plan.
• From the command line or MCP: stair_railings_add (with near for the side nearest a point) and railing_host_set (put an existing railing on a stair or ramp, on the side its path runs along unless side is given; change its side or inset; or detach it).

Shafts

Architecture → Floors & Roofs → Shaft (SF) sketches the outline of a vertical opening (a duct chase, a lift or stair shaft, a light well) in a plan, like a floor’s outline; it rises from its level to the highest level above (or a level or height set in its properties). A project without a shaft type gets one the first time.

• What it cuts: every floor, ceiling and roof it passes through, where its outline lies inside theirs and clear of their own openings. The cuts follow the shaft when it moves, changes or is deleted, in the same undo step; plans, areas in schedules, 3D views and IFC export show them like any opening. A shaft across the edge of a slab does not cut it.
• In plans: its outline crossed by two diagonals, in the plan of its level and in every plan whose cut plane it passes through.
• Properties: the base offset, the top (a level plus an offset, or unconnected with a height), its height and area. Edit Boundary opens its outline again. element_get lists the elements it cuts (derived.cuts).

Swept profiles

Architecture → Model → Sweep (SW) carries a profile along a path drawn in a plan: baseboards, crown moldings, fascia boards, gutters, copings. A project without a sweep type gets one the first time (a baseboard 1.5 × 10 cm).

• Drawing: click the points of the path; Enter, a double click or Finish ends it, and Backspace removes the last point. The options bar sets the height of the path above the level, Closed path (it runs back to the first point, around a room, with no ends) and Flip side.
• Which side: the profile is drawn in its own plane, square to the path: x across, to the left of the path walking along it, and y up from the path’s height. Flip side puts it on the right; a mirrored copy keeps it on the same side of the wall it follows. Corners are mitered.
• Profiles: the type holds the profile and the material. sweep_type_create makes a type from points [x, y] or from curves (lines, arcs, circles, rectangles… making one closed outline, so a cove or a half-round gutter is drawn with arcs), and sweep_profile_set redraws a type’s profile; both are in the command palette. A profile must be a closed outline that does not cross itself.
• Edit Profile (Modify → Sketch, with one sweep selected, or the button in its type’s Edit Type…) opens the type’s profile in a sketch that takes the place of the views: its plane has x across (outward, to the left of the path) and y up from the path, the path’s point marked where the axes cross. The sketch has the usual ribbon, drawing and Modify tools, grips and undo; points snap to the sketch’s own points, the path’s point, the axes and millimeters. Finish redraws the profile of every sweep of the type in one undo step (an open or crossing outline is refused and shown), Cancel leaves it as it was. The type keeps the curves, so a cove’s arc is still an arc when the profile is edited again; changing the profile’s points another way drops them.
• Views: plans and ceiling plans draw what the cut plane cuts and what lies below (or above, in ceiling plans), elevations, sections and 3D views show the solid, legends show the profile’s section, and schedules list the length and volume. IFC export writes them as coverings of type MOLDING.

Drafting views

• View → Drafting View (also the + of Drafting Views in the project browser) creates a 2D view that is independent of the model: it shows no walls, floors or other model elements, only what is drawn in it — text notes, dimensions and imported CAD drawings or images. It is meant for standard details and other drawings that are not cut from the model.
• It has its own scale (1:10 by default; 1:1, 1:2 and 1:5 are in the list too) and detail level, set in its properties, and its own Visibility/Graphics for the annotation and imported drawing categories (it has no template, phase or visual style, since it does not show the model).
• The Text, Dimension, Import CAD and Import Image tools work in it as in other 2D views; dimensions in it measure only what they are drawn on.
• Drag it from the browser onto a sheet like any other view, and export it with Export Image, Export PDF, Export SVG or Export DXF. Deleting it deletes what was drawn in it.

Callouts and detail views

• View → Callout draws a callout in the active floor plan, ceiling plan, section or elevation (greyed out in other views, saying why): click two opposite corners of the region to detail. It makes a detail view of that region at a larger scale, listed in the project browser under the parent’s kind (Floor Plans, Sections…), that stays live with the model and is cropped to the rectangle; draw detail lines, regions, detail components, texts and dimensions in it as in any view. The options bar picks the scale (Automatic: about five times larger than the parent’s) or, under Shows, an existing drafting view the callout points to instead of a new detail view.
• The parent draws the callout as a rectangle with rounded corners and a tag with the detail’s number over the sheet’s number once the detail is placed on a sheet. With the Select tool, click the callout to select it (its view’s properties show, with Open View and Remove Callout), drag it to move it or drag a corner to resize it — the detail view’s crop follows — and double-click it to open its view. Delete deletes the detail view, which removes the callout.

Detail lines

• Annotate → Detail Line (DL) draws 2D lines that belong to the active view only: a floor plan, ceiling plan, elevation, section, legend or drafting view (the button is greyed out in other views, and says why). They are drawn on top of the model and show nowhere else.
• The options bar picks the mode — Line, Polyline (lines chained end to end until the polyline closes or Esc), 3-point arc, Center arc, Circle, Ellipse and Rectangle — and the line style: Thin, Medium, Wide, Hidden, Dashed, Center or Dotted. Points snap to the model, imported drawings and other detail lines (ends, middles, centers, quadrants). Each curve becomes an element as soon as it is drawn (one per segment of a polyline or side of a rectangle); Esc drops the curve in progress, a second Esc leaves the tool.
• Selected, a detail line shows its style, view, shape, length and radius in the properties palette, where the style can be changed, and grips at its ends, an arc’s middle, a circle’s or ellipse’s center and on their outline to reshape it. Move, Copy, Rotate, Mirror, Array and Delete work on it, in drafting views, elevations and sections too (there they take only what the view owns: detail lines, texts and dimensions); Trim/Extend to Corner, Trim/Extend, Split and Offset work on its curve (two detail lines meet at a corner; a detail line also trims to a wall, beam or grid; circles split into halves; arcs and circles offset concentric).
• Visibility/Graphics hides or overrides them with the Detail line category. They print on sheets, export with the view (DXF puts them on a layer named after their style) and are left out of 3D views and IFC.

Line styles, filled and masking regions

• Annotate → Line Styles opens a dialog with the built-in line styles (read only) and the project’s own: their name, weight, color and dash pattern are edited in place, and the table says how many elements use each. New adds a style; Delete removes the selected one, and what used it moves to the Thin style. OK keeps the changes, Cancel undoes them all. The line-style lists of the Detail Line tool, of a selected detail line and of a region’s boundary show the project’s styles after the built-in ones.
• Annotate → Filled Region (FR) and Masking Region open the sketch mode in the active floor plan, ceiling plan, elevation, section, legend or drafting view (greyed out in other views, saying why): draw the boundary with the sketch tools — loops inside the outline become openings — and click Finish. A filled region is filled as its type says (pick the type in the options bar’s type list; the first region makes a type with diagonal lines over white) and edged in the thin style; a masking region is opaque white with no boundary and hides the model’s lines under it. Both are drawn over the model and under the view’s annotations (detail lines, dimensions, texts, tags, grids), in that view only.
• Selected, a region shows its boundary style (any line style, or None), view, area, perimeter and number of openings in the properties palette, and its type in the type list. Edit Boundary (Modify tab) reopens its sketch in its own view. Move, Copy, Rotate, Mirror and Delete work on it, outside plans too. Edit Type shows a filled region type’s Fill: a foreground and a background pattern, each with its color (a Solid pattern fills with its color; a None background lets the model show between the pattern lines).
• Visibility/Graphics hides or overrides them with the Filled Region and Masking Region categories. They print on sheets and export with the view (DXF puts their fills as solids and their pattern lines on a layer named after the boundary’s style) and are left out of 3D views and IFC.

Detail components

• Annotate → Detail Component (DC) places a detail component — a reusable 2D component for construction details — in the active floor plan, ceiling plan, elevation, section, legend or drafting view (greyed out in other views, or when the project has none, saying why). The options bar’s type list picks the component, and rotation (with a Turn 90° button), scale and Mirrored set how it lands; it follows the cursor, snapping like the other tools, and a click places it. It is drawn over the model and its regions, under detail lines and annotations, in that view only.
• Annotate → Create Detail Component turns the selected detail lines, regions, texts and detail components of the active view into a new detail component type (named Detail 1, Detail 2…; rename it in its type properties), placed where they were, in one undo step. A detail component may hold others (nested), never itself.
• Selected, a placed detail component shows its component and view, and its rotation, scale and Mirrored in the properties palette. Move, Copy, Rotate, Mirror and Delete work on it, outside plans too. Its pieces are edited with the component_sheet_piece_* commands from the command palette (the component editor is for 3D components).
• Insert → Component Library lists detail components with the others (their kind is 2D detail) and loads them, with the components they nest. Next to Insert → Import CAD…, Blocks as components brings a DWG or DXF file’s blocks in as detail components placed where the file inserts them, instead of exploding them into the imported drawing.
• Visibility/Graphics hides or overrides them with the Detail component category. They print on sheets and export with the view (DXF writes them as blocks and inserts) and are left out of 3D views and IFC.

Imported CAD drawings

• Insert → Import CAD… places a DWG or DXF drawing in the active floor plan, ceiling plan, elevation, section, legend or drafting view (the button is greyed out in other views, and says why). You can also drop .dwg and .dxf files on the window. The file dialog starts in the Projects folder. The drawing keeps its origin at the view’s origin, unless that leaves it more than 1 km from the model (a drawing in survey coordinates), then it is centered on what the view shows. The status bar says how many items and layers were read, how many entities were not drawn (3D solids, images, infinite lines…) and which units were assumed when the file has none.
• Insert → Import Image… places a picture (PNG, JPEG, GIF, BMP, WebP) or an SVG drawing in the active view, the same views as Import CAD, centered on what the view shows; dropping such a file on the window does the same. A picture is as large on paper as its resolution makes it (96 dpi when the file declares none): set Scale in its properties (100 for a plan scanned at 1:100) or width in image_import. An SVG keeps its paths, fills and embedded pictures in their own colors (its texts are not read). It is an imported drawing like a DWG: pinned, moved, turned and hidden the same ways, printed and exported with the view.
• File → Export DXF… (also Insert → Export DXF…) writes the active view (any view but a schedule) as a DXF drawing for other CAD programs, as printed: plans, elevations and sections at full size in millimeters (texts at their printed height times the view’s scale), a sheet in paper millimeters. Each element goes to the layer of its category (WALL, DOOR…; annotations to ANNOTATION and TEXT), dashed and dash-dot lines get line types, opaque fills become solids, and colors are the nearest color index, so a plot style by color can give the pens their weights. The file is DXF R12, which every CAD program opens; it reads back with Import CAD.
• The drawing is a background to trace over: thin grey lines under the model, with its texts. It shows only in the view it was imported into (not in other plans or in 3D views), prints on sheets and exports, and is left out of IFC export. Visibility/Graphics hides or overrides it with the Imported CAD category.
• It starts pinned, so it is not moved by accident; Unpin it to move or rotate it with the usual tools. Clicking its lines selects it only where no model element is under the pointer.
• Its properties set the units (read from the file, else assumed), an extra scale, the rotation, the position of its origin, the colors (Grey, Layer colors with very light colors darkened for white paper, or Black) and Halftone. The Layers section shows or hides each layer (All layers toggles them all); layers that are off or frozen in the file start hidden.
• The drawing tools snap to its endpoints and vertices, midpoints, arc and circle centers (a circle marker), and to points on its lines.
• Modify → Explode (also the Explode button in its properties) turns the selected imported drawing into native elements of its view, in one undo step: its lines, polylines, arcs and circles become detail lines (one per segment; ellipses and splines come out as their segments), its fills filled regions of a solid type of their color, its texts text notes of a type of their size on paper. Each layer becomes a line style of its name and color (Annotate → Line Styles), reused when one of that name exists; hidden layers are left out, and the result lands where the drawing was (units, scale, rotation, mirror). Pictures stay as an imported drawing; the color mode and halftone are not carried over. What it made is selected. A drawing that would make more than 100,000 elements is refused: hide layers first.

Construction phases

• Manage → Phases has three tabs. Phases lists the project’s phases from earliest to latest with their name, description and how many elements are built and demolished in each; Add appends one, Insert Before puts one before the selected phase, ↑ ↓ reorder (a move that would put a demolition before its construction is refused), and deleting a phase moves its elements and views into the phase chosen under Merge elements and views into. Phase Filters sets, for each filter, how existing, demolished, new and temporary elements show: Not Displayed, By Category or Overridden. Phase Graphics sets the overrides used for each status (the same cells as Visibility/Graphics). OK keeps the changes, Cancel undoes them.
• The view’s properties (plans, elevations, sections, 3D views, schedules) have a Phasing section with its Phase and Phase Filter; the filter is read-only when the view’s template controls it. Elements show Phase Created and Phase Demolished. New elements are built in the active view’s phase.
• Modify → Demolish (DE) demolishes the clicked elements in the active plan’s, elevation’s or section’s phase; their doors and windows go with them.

Sheets and title blocks

A sheet’s properties set its number, its title block (a title block type of the project, or None for blank paper), its paper size (A0 to A4, or Custom with a width × height in millimeters between 50 and 5000) with Portrait to put the long side up, and its issue date (typed as YYYY-MM-DD; Today fills it in). Sheet Fields lists the title block’s per-sheet fields: type a value for this sheet, or leave the row empty to use the title block’s own text, shown greyed. When a piece of the active sheet’s title block cannot be drawn (an expression that does not resolve), the status bar names it.

Manage → Project → Project Information has a Project fields table: your own values, such as the engineer or the permit number, each with a name and a value. + Add field adds one, a name is changed by typing over it (Enter), × removes it. Title blocks show them as {project:Name}.

A title block draws the whole sheet: border, margins, the block itself, logos. It is a component (category Title Blocks), so it is saved to and loaded from .ccomp files and the component library. Modify → Title Block → Edit Title Block (or Edit Title Block in a sheet’s right-click menu, in the view or the project browser) opens the active sheet’s title block in the editor; View → Documentation → New Title Block makes one from the standard layout and opens it; loading a title block from the library opens it too.

• The Sheet view: the editor shows the paper at a preview size: the sheet it opened from, or A0 to A4 in portrait or landscape (Preview on, in the options bar). Its four edges are locked reference planes. The wheel zooms, a middle or right drag pans, a middle double-click fits the sheet.
• Lines: opens a sketch with the drawing and modify tools of Sketching outlines. Finish makes a stroke of each chain of curves, closed when its ends meet. A point on an edge is written SheetWidth, SheetHeight or 0, and a point on a reference plane as the plane’s name, so the stroke follows the paper: a line drawn on the right edge of an A3 stays on the right edge of an A1. Other points are kept to the hundredth of a millimeter. Lengths typed while drawing are lengths on the printed paper. A stroke’s properties set its weight (millimeters), color and, when closed, its fill; Edit Sketch (or a double click) opens it again.
• Text: a click places a text. Its properties set the words, the height, the alignment (left, center or right on the baseline, or the middle of the block), the rotation and the position. Insert field adds a field at the cursor: sheet number, name, count and position, scale and paper; project name, number, client, address, author and project fields; today’s date and the issue date; and the per-sheet fields. Fields show filled in from the sheet the editor opened from (or sample values); Show field keys shows them as typed, such as {sheet_number}. {{ writes a brace.
• Image: pick a PNG, JPG or SVG file, then drag its rectangle; the picture keeps its proportions unless Shift is held. Its corner grips move and size it. The picture is kept in the title block (and in its .ccomp file).
• Reference Plane: two clicks along a line make a plane square to the paper. Its position is an expression in millimeters that may read the paper (SheetWidth - 10).
• Parameters: numbers (in millimeters) and texts. New per-sheet field adds a text that each sheet may set in its Sheet Fields; the parameter’s text is the default. Sheet width and Sheet height show the preview’s paper.
• Selecting: click a piece, or drag a window around several; Delete removes them. A picked text or picture shows grips.
• Finish keeps the changes and Cancel Editing undoes everything done in the editor. Every sheet that uses the title block follows.

Component modeling environment

Edit Component (Architecture → Model, or Edit Component… in a component type’s properties) opens a workspace of its own for the selected component, or the one the Component tool places. Quick Edit… keeps the older one-window editor.

• Views: the project’s views give way to the component’s Plan, Front, Side and 3D views. The wheel zooms, a middle or right drag pans, and a middle double-click fits the view.
• Ribbon: the Create tab holds Select, Extrusion, Revolution, Sweep, Blend, Reference Plane, Dimension, Equality (EQ), Connector, Save Component…, Finish and Cancel Editing.
• Left panel: the type whose values the views show, the parameters (name, value, whether elements may override it, ×, and + Parameter) and the properties of the selected plane, dimension, piece or connector.
• Reference planes: three origin planes are always there: CenterX (center left/right), CenterY (center front/back) and Base. Reference Plane takes two clicks in the plan, front or side view; a mostly vertical or mostly horizontal line sets which way the plane faces. A plane’s position is an expression (Left + Width), and its name can be used in any expression of the component, so a piece that reads x = Left follows the plane.
• Dimensions: Dimension takes two parallel planes, then measures them where you clicked. In its properties, a Label (a length parameter, or a new one typed under New parameter) makes the parameter drive the second plane. Changing the value changes the parameter, or moves the plane when the dimension has no label.
• Sketched pieces: Extrusion, Revolution, Sweep and Blend open a sketch, the same as outlines in plans (see Sketching outlines): its ribbon (Sketch: Extrusion…) has the drawing tools (lines, rectangles, polygons, circles, ellipses and arcs), the Modify tools, Finish and Cancel; curves are picked, stretched by their grips and typed in the side panel. Draw in the plan, front or side view: the first curve fixes the view. Points snap to the sketch’s own points and to reference planes, and a coordinate on a plane seen edge-on is locked to it, so the piece follows the plane; points on a circle or an ellipse whose center is on a plane are written from that plane. The options bar sets Solid or Void. Finish makes an extrusion at once; a revolution then asks for its axis, a plane seen as a vertical line or any point (Esc goes back to the outline). The new piece is selected: its properties set the name, Void, Shown in plans, the material and where it starts and ends (or its axis and angle), each an expression that the ⌖ menu locks to a plane. Edit Sketch in its properties opens its outline (a sweep’s path, a blend’s bottom then top) again; points that did not move keep the expressions they were written with.
• Equalities (EQ): Equality (EQ) takes three parallel planes in one view: an outer one, the one kept halfway, then the other outer one. The middle plane’s position becomes (a + b) / 2, so it stays centered as the others move; the view shows two dimensions marked EQ. Moving the middle plane by hand would break it and is refused; delete the equality first.
• Connectors: where pipes and conduits join the component (a fixture’s water inlet and drain, an outlet’s electrical connection). Connector places one with a click in the plan, front or side view; a coordinate near a reference plane seen edge-on is locked to it, so the connector follows the plane, and the depth starts at 0 (in plan it points down, elsewhere back). Every view, the 3D one too, shows connectors as rings in their system’s color with an arrow the way runs leave (a dot when that is toward you, a cross when away). Their properties set the name, the kind of system, X, Y and Z (expressions the ⌖ menu locks to a plane), the direction and the diameter. A run drawn to a placed component joins it at its connectors (component_connector_add, _set, _delete).
• Sketch points: a sketched piece’s properties list its points (and a sweep’s path and section, a blend’s top). Each coordinate is an expression; type a new one, or lock it to a plane seen edge-on in the sketch’s view with ⌖.
• Sweeps and blends: a Sweep’s curves are an open path; a section is carried along it, set in the options bar as a rectangle (width × height) or a circle (diameter), centered on the path; corners are mitered. Blend takes a bottom outline, then (after Finish) a top outline drawn in the same view, and joins them; its start and end are set in its properties like an extrusion’s.
• Selection and keys: click a plane’s line, a dimension’s text, a piece’s edge or a connector to select it; Delete removes it, and Esc steps back through the tool’s picks, the tool and the selection.
• Script pieces: + Script in Quick Edit… adds a script piece with a starter script; its source is edited in the piece’s properties, and what it declares becomes the component’s parameters (their names, kinds and instance flags come from the script; only their values change in the table). A script that does not load is reported above the piece. See Scripted components. In the properties palette, a placed scripted component shows Instance Parameters and Type Parameters · shared (checkboxes, text boxes, lists of choices and of materials) and any Script Errors; selected in a plan, its hotspots show as grips in their shape and color, and dragging one moves it.
• Finish and Cancel: every change applies to every type of the component and undoes like any other edit. Finish keeps them, Cancel Editing undoes everything done since the environment opened.

Preferences

File → Preferences (Ctrl+,, also at the bottom of the home screen) holds the settings of the app itself; they are not part of any project and are kept between sessions. Pick a page on the left. Changes show at once; OK keeps them and Cancel (or Esc) brings back the values the window opened with. Restore defaults (bottom left) resets the settings of the page shown; the language and the folders stay as they are.

• General: the interface language, the theme (light, dark or the system’s) and Check for updates automatically (see the update notice below).
• Interface: the Interface scale (75–200%, everything grows: panels, icons, text; Ctrl+Plus and Ctrl+Minus change it too), the Text size (small, normal, large, extra large; only the text, at any scale), Start with the ribbon collapsed, Detailed tooltips (when off, command tooltips show only the name, the shortcut and why a command is unavailable, without the description and the engine command) and Dragging in 3D views selects (a left drag draws a selection box and Shift+drag orbits; off, the other way round).
• File locations: the Macros folder (the macro file dialogs start there and Manage → Run Macro lists its macros), the Projects folder (where Open, Import IFC, Import CAD and the first Save of a new project start; a saved project is saved again next to itself), the component library folders (Add Folder…, Remove) and the Plugins folder (see Plugins; not set, a plugins folder in the app’s data folder). The component library window’s Manage Folders… opens this page. A folder that no longer exists is marked Not found and skipped.
• Saving: the Autosave interval (off, or every 1, 2, 5, 10 or 15 minutes; see below) and how many recent projects the home screen lists.
• Keyboard shortcuts: every command with its keys. Click a command’s box and type two letters to give it new keys (they replace the old ones at once, in tooltips, the palette and views); keys another command already has are refused and the row says which. Leave the box empty to take the keys away, and Default brings back the original ones. Search finds a command by name or keys. Ctrl shortcuts, Delete and Esc are fixed.

Visual programming

Manage → Macros → Visual Programming opens the graph editor in a panel under the views, so the model and the graph are seen together (constructcraft project.ccad --graph file.ccgraph opens one at startup). A graph is a set of nodes joined by wires (see Visual programming graphs for what the nodes do and how running again updates the model).

• Adding nodes: double-click or right-click the background to open the node search; type words of the node’s name, group or description and press Enter (or click a match). Every engine command is a node, next to the built-in nodes (inputs, math, logic, lists, geometry, parameters, outputs) and the Lua node.
• Wiring: drag from an output (right side) to an input (left side), or the other way. Dragging from a wired input picks its wire up. Ports are colored by type; a wire between types that do not fit is refused with a message in the status bar.
• Moving around: drag a node to move it (with the others selected); drag the background to select with a box (Shift or Ctrl adds); the middle or right button pans; the wheel zooms about the pointer. Zoom to Fit frames the graph.
• Inputs: number, integer, slider, boolean and text nodes have their value on the node. The inspector on the right edits the selected node: its name (on input and output nodes, the name of the graph’s input or result), the list lacing, the values of its unwired inputs (JSON, or plain text), a command node’s Show all inputs, a Lua node’s inputs, outputs and code, and Use Selection on select_elements. It shows the node’s outputs, error or reason it was skipped after a run. With no node selected it shows the graph’s name, Allow file commands, how many elements the graph made, Select Elements and Release Elements.
• Running: Run (F5) runs the graph through the engine as one undo step; the toolbar and the status bar show how many elements were created, changed and deleted. Automatic runs it after every change. Each node shows its value (or error) under it; clicking a node selects the elements it made.
• Keys while the pointer is over the panel: Delete removes the selected nodes, Ctrl+C / Ctrl+V copy and paste them, Ctrl+A selects all, Ctrl+Z / Ctrl+Y undo and redo graph edits (the model’s own undo is on the quick access toolbar), Ctrl+S saves the graph.
• Files: New, Open…, Save, Save As… work with .ccgraph files (the dialogs start in the macros folder). Closing the panel, New or Open… with unsaved changes asks first.

Plugins

Plugins add commands to ConstructCraft (see Plugins in the automation guide). Manage → Plugins holds two buttons: Plugins… opens the Plugins window, and Plugin Commands is a menu of the installed plugins’ commands, by plugin; choosing one opens its form in the command palette, where Run executes it as one undo step and shows what the plugin printed. The palette also finds plugin commands by name.

The Plugins window has two tabs:

• Installed: the plugins of the plugins folder. Pick one to see its version, authors, license, page, commands and any error from loading it. Turned on loads it or leaves it out (a plugin turned off runs no code). A plugin that asks to work with files has Allow it to read and write files; without it, its commands that import, export or save are refused. Remove deletes it from the folder.
• Available: the plugins of the community index, read when the tab is first opened (Refresh reads it again). Install (or Update to …) downloads the newest version this build can run, checks it against the index’s checksum, and installs it only if it loads; a plugin that asks for files gets the permission only when you tick the box first.

Only this tab reaches the network: it reads the index and the archives it lists, over HTTPS, when you ask. Reload Plugins reads the folder again, after you add or edit a plugin by hand. Plugins are loaded when the app starts and stay loaded when you open another project.

Update notice

ConstructCraft tells you when a newer version is published; it never downloads or installs anything by itself, only when you choose Update Now.

• When: at startup, at most once a day, in the background (the window never waits for it). File → Check for Updates (also in the About dialog) checks at once and reports “up to date”, the new version, or that it could not check.
• What is contacted: one HTTPS request to the GitHub API, https://api.github.com/repos/francisreboucas/constructcraft/releases/latest, which returns the latest published release. The request sends the usual connection data (your IP address) and a ConstructCraft/<version> user agent; no project data, identifier or usage information. GitHub’s privacy statement applies to it.
• What you see: when the release is newer than the running version (pre-releases are ignored), a notice appears in the status bar and on the home screen: Download opens the release page in your browser, Skip This Version hides the notice until a later version comes out, and × hides it until the next check. Any failure (offline, timeout, proxy, rate limit) is silent.

• Update Now: where ConstructCraft can replace itself safely, the notice and the check’s dialog offer Update Now. It downloads the package that fits how this copy was installed and checks its SHA-256 against the release’s SHA256SUMS.txt (both from the release’s own download links on GitHub) before anything changes; a download that does not match is deleted and the installed copy is left as it was.

  Installed as	Update Now does
  AppImage	Downloads the new AppImage next to the old one, checks it, renames it over the old file and offers Restart Now
  Windows installer (.msi, under Program Files)	Downloads and checks the installer; it runs when ConstructCraft closes (Install Now closes it, asking about unsaved changes first; On Exit waits), and ConstructCraft opens again when it is done
  Windows .zip	Downloads and checks the archive, puts the new constructcraft.exe and ccad.exe in place (the old ones are kept as .old and removed at the next start) and offers Restart Now
  macOS app	Downloads and checks the disk image and opens it: drag ConstructCraft to Applications
  .deb	Nothing: the dialog shows the apt command, with Copy, and Download gets the package
  .tar.gz, builds from source	Nothing: Download opens the release page

  Update Now needs write access to the installed files: an AppImage in a folder you cannot write to fails with a message, and Download is the way to update it.

• Turning it off: clear Check for updates automatically in Preferences → General. The environment variable CONSTRUCTCAD_NO_UPDATE_CHECK=1 turns off every check, automatic or on request (useful for CI, kiosks and offline installations). ConstructCraft remembers the last check time, the skipped version and the setting with its other preferences.

Autosave and recovery

A minute after a project gets unsaved changes (a new project that was never saved too; Preferences → Saving sets another interval or turns autosave off), ConstructCraft writes a copy of it, in the background, to the recovery folder of its data folder (%APPDATA%\ConstructCraft\data on Windows, ~/Library/Application Support/ConstructCraft on macOS, ~/.local/share/constructcraft on Linux). It writes again only after the model changes, and never over your project file. Saving, closing the project or quitting removes the copy.

If ConstructCraft crashes or is killed, the next start shows Recover Unsaved Work with the copies left behind: Restore opens the chosen project with its unsaved changes (saving it writes to its original file, or asks where for a project that was never saved), Discard deletes the copy, and Cancel keeps the copies for the next start. A crash in the interface also writes a last copy before the app closes, and every crash is appended to crash.log in the data folder; attach it when you report a crash.

Graphics start-up

ConstructCraft draws with the system’s native graphics API (DirectX 12 or Vulkan on Windows, Metal on macOS, Vulkan on Linux) and falls back to OpenGL by itself when that fails, which some older or small integrated GPUs need:

• If the native API reports an error, the same start tries OpenGL. If it crashes before the window appears, ConstructCraft starts again once with OpenGL; if the whole process dies (a driver crash), the next start tries OpenGL first.
• Once OpenGL was needed, it stays first: the choice is kept in the file gpu-backend of the data folder. Delete that file (after updating the graphics driver, for example) to try the native API again.
• Every failed start is written to crash.log in the data folder. When no API works, a message says so and names that file.
• The environment variable WGPU_BACKEND picks the API yourself and turns the fallback off: gl for OpenGL, dx12, vulkan or metal, or several separated by commas (on Windows, for example, set WGPU_BACKEND=gl in a command prompt before starting constructcraft.exe, or as a user environment variable). WGPU_POWER_PREF=low prefers the integrated GPU on computers with two.

Accessibility

The ribbon buttons, tab titles, scroll arrows, palette entries, browser rows, home screen cards, dialog close buttons, property sections and the view cube’s home button are drawn by ConstructCraft itself. They report their role (button, selectable item, collapsible header), their name and their state (enabled, selected, expanded) to the operating system’s accessibility interface, so screen readers can announce them.

For developers

Adding a command to the interface

1. Make the change an engine command first (see For developers in the automation guide).
2. Add a variant to UiCommand in crates/cc_app/src/commands.rs. Then fill in its icon, label, description (an i18n key cmd-desc-… in every .ftl file), shortcut (if any), engine (the engine command’s name), badge, unavailable (a localized reason for each state in which it cannot run), selected (for tools) and run. Add it to UiCommand::all.
3. Place it in a ribbon group with command_button (large) or in a family of small buttons with stacks (crates/cc_app/src/ribbon.rs).

The tooltip, enabling, the palette entry and a two-letter shortcut all follow from the command. Tests check that each engine name exists in the catalog, that shortcuts are unique, and that every command appears in the ribbon with an accessible name.

Icons

Icons are SVG files in assets/icons/ui on a 24-unit grid. They use white strokes (stroke-width 1.75, round caps and joins) and soft fills written as fill="#fff" fill-opacity=".2". icons.rs splits each icon into two layers by those attributes: the strokes and solid marks form the ink, and the soft fills form the tint. Each layer is rasterized with resvg at the exact pixel size and painted in the theme’s colors (icons::Tones). Add the new icon to Icon, Icon::ALL and Icon::source. ICON_SHEET=sheet.png cargo test -p cc_app icon_sheet writes every icon at several sizes for review.

Theme

Colors are tokens of theme::Palette: PALETTE (light) and DARK, with a test of their contrast. Paint with theme::palette(ctx) so a dark theme can be switched on later.

Interface tests

crates/cc_app/src/ui_tests.rs runs the ribbon and the palette headlessly with egui_kittest. The tests click and type through the accessibility tree, so custom widgets must call Response::widget_info. Screenshot references live in crates/cc_app/tests/snapshots. They cover each ribbon tab, the narrow and collapsed ribbon, a rich tooltip, the palette, each page of the Preferences window, and an icon gallery in both themes. GPUs render slightly differently, so the screenshot comparisons run on request:

CC_UI_SNAPSHOTS=1 cargo test -p cc_app snapshots     # compare with the references
UPDATE_SNAPSHOTS=1 cargo test -p cc_app snapshots    # rewrite them after an intended change

Review the new images before committing them. On a mismatch, kittest writes *.new.png and *.diff.png next to the references; Git ignores those files.

This site is open source. Improve this page.