.fcc Component Structure

This document describes the standard folder structure and file conventions for a HiStruct component package.

A component template is stored in a folder ending in .fcc. That folder contains the FCS source, metadata, views, reports, and static assets that define how the component behaves.

Folder Layout

MyComponent.fcc/
├── .fcsconfig.json        ← {"EngineVersion":"e4.trans"}
├── Main.fcs               ← Root entry point
├── fcscdm.json            ← Component manifest (HumanName, Views, Reports, ParameterDescriptions)
├── Views.fcscdx           ← View definitions (camera presets, projection settings)
├── Inputs.fcs             ← Fcs.Parameter.Item* declarations (UI form)
├── Pvc.fcs                ← Parameter-value constraints
├── *_updated.fcs          ← Test snapshot (parameter overrides for eval entry point)
├── *_viewAll.fcs          ← View-all entry (imports Main.fcs)
├── ProjectionSettings.fcsdrv ← Camera/projection JSON for 3D view
├── Reports.fcscdx         ← Report templates
└── static_files/          ← Thumbnails, images

Purpose of Each File

.fcsconfig.json

Defines which engine/runtime compatibility mode the component should use.

Example:

{
  "EngineVersion": "e4.trans"
}

Main.fcs

The root evaluation entry point.

This file usually:

Example:

module MyComponent.Main

let inWidth_m = 4.5
let inLength_m = 10.0
let outArea_m2 = inWidth_m * inLength_m

fcscdm.json

The component manifest.

This file tells the platform how the component should be presented and evaluated.

Views.fcscdx

Defines available views, camera presets, and how the 3D presentation should behave.

Inputs.fcs

Defines parameter UI items using Fcs.Parameter.Item* declarations.

Pvc.fcs

Defines PVC-related rules, constraints, defaults, and value validation logic.

*_updated.fcs

A test-oriented snapshot entry point that commonly contains parameter overrides used for evaluation experiments.

*_viewAll.fcs

A helper entry point used for broad or overview visualizations, usually importing Main.fcs.

ProjectionSettings.fcsdrv

Holds projection or camera settings for a 3D view.

Reports.fcscdx

Contains report templates and report layout configuration.

static_files/

Contains static assets such as:

fcscdm.json Manifest

The manifest is the metadata bridge between the .fcc folder and the platform UI.

Key fields

FccRef

The component reference used by the platform to identify the template.

Example:

{
  "FccRef": "MyComponent.fcc"
}

ParameterDescriptions

Describes input and output parameters for UI and metadata display.

Typical uses:

Views

Lists the available named views the component can render.

Typical uses:

Reports

Lists the report definitions available for the component.

Typical uses:

EvaluationEntryPoint

Defines the primary evaluation entry point used when the component is executed.

Example skeleton:

{
  "FccRef": "MyComponent.fcc",
  "EvaluationEntryPoint": "Main.fcs",
  "Views": ["viewDefault"],
  "Reports": ["reportSummary"],
  "ParameterDescriptions": []
}

.fcsconfig.json

Supported EngineVersion values:

Recommendation

For new projects, use:

{
  "EngineVersion": "e4.trans"
}

This is the recommended default for modern component development.

Views.fcscdx

Views.fcscdx defines named views and must be authored carefully.

Important requirements

Example shape:

<View Name="viewDefault">
  <ProjectionSettingsFile>ProjectionSettings.fcsdrv</ProjectionSettingsFile>
</View>

If either the projection settings reference or encoding is wrong, the component may fail to render correctly in the 3D viewer.

Parameter UI Items

HiStruct parameter forms are declared with Fcs.Parameter.Item* constructs. These define what the user can edit in the component UI.

Below are the common item types.

ItemDouble

Numeric floating-point input.

Fcs.Parameter.ItemDouble(
    Name = "inWidth_m",
    HumanName = "Width",
    DefaultValue = 4.5
)

ItemInteger

Integer input.

Fcs.Parameter.ItemInteger(
    Name = "inPanelCount",
    HumanName = "Panel count",
    DefaultValue = 6
)

ItemList

Selectable choice from predefined options.

Fcs.Parameter.ItemList(
    Name = "inRoofType",
    HumanName = "Roof type",
    AllowedValues = ["gable"; "hip"; "shed"],
    DefaultValue = "gable"
)

ItemArray

Collection-style input for repeated items.

Fcs.Parameter.ItemArray(
    Name = "inSegments",
    HumanName = "Segments"
)

ItemClass

Structured group of related fields.

Fcs.Parameter.ItemClass(
    Name = "inFrame",
    HumanName = "Frame settings"
)

ItemAction

UI-triggered action item.

Fcs.Parameter.ItemAction(
    Name = "inRecalculate",
    HumanName = "Recalculate"
)

ItemComment

Read-only descriptive text shown in the parameter UI.

Fcs.Parameter.ItemComment(
    Name = "infoGeometry",
    HumanName = "Geometry notes",
    Text = "Adjust width and length to update the preview."
)

ItemString

Free-text input.

Fcs.Parameter.ItemString(
    Name = "inProjectName",
    HumanName = "Project name",
    DefaultValue = "Demo project"
)

ItemGallery

Image or gallery-style selection UI.

Fcs.Parameter.ItemGallery(
    Name = "inCladdingStyle",
    HumanName = "Cladding style"
)

ItemToggle

Boolean on/off switch.

Fcs.Parameter.ItemToggle(
    Name = "isInsulated",
    HumanName = "Insulated",
    DefaultValue = true
)

Example Inputs.fcs

module MyComponent.Inputs

let parameters = [
    Fcs.Parameter.ItemDouble(Name = "inWidth_m", HumanName = "Width", DefaultValue = 4.5)
    Fcs.Parameter.ItemDouble(Name = "inLength_m", HumanName = "Length", DefaultValue = 10.0)
    Fcs.Parameter.ItemList(Name = "inRoofType", HumanName = "Roof type", AllowedValues = ["gable"; "shed"], DefaultValue = "gable")
    Fcs.Parameter.ItemToggle(Name = "isInsulated", HumanName = "Insulated", DefaultValue = true)
]

Naming Conventions

Use consistent prefixes and suffixes so that intent is obvious in code, UI, and API responses.

Prefix Meaning
in* User-editable input parameter
out* Computed output (read-only)
is* Boolean flag
_m Value in metres
_deg Value in degrees

Examples

Practical Guidance

When creating a new .fcc package:

  1. Start with .fcsconfig.json using e4.trans
  2. Put your main logic in Main.fcs
  3. Define user-editable parameters in Inputs.fcs
  4. Keep PVC-related rules in Pvc.fcs
  5. Register views in Views.fcscdx
  6. Add metadata to fcscdm.json
  7. Store thumbnails and supporting assets in static_files/

A clean .fcc folder structure makes the component easier to evaluate, publish, debug, and maintain.