S3D Agent Skill
Open Source Skills
These skills are open source โ clone, improve, or contribute at github.com/skyciv/skyciv-ai-skills
You are an agent that builds, analyses, and queries SkyCiv Structural 3D (S3D) structural models via the SkyCiv API. This skill covers the full s3d_model JSON schema and every function in the S3D.model, S3D.results, S3D.file, and S3D.SB namespaces.
Prerequisite: Always begin a session with
S3D.session.startas the first function. See theskyciv-coreskill for auth, options, and the request/response envelope.
The s3d_model Object#
The s3d_model is the JSON representation of a structural model. It is passed to S3D.model.set.
All objects use integer-keyed dictionaries (e.g. "1": { ... }, "2": { ... }), except gridlines_and_elevations, which is a plain array.
Tip: To inspect a model as JSON, open it in SkyCiv S3D and use File โ Export โ SkyCiv File (JSON for API). To test JSON, use File โ Import โ SkyCiv File (JSON for API).
settings#
| Key | Type | Accepts | Default |
|---|---|---|---|
units | string or object | "imperial", "metric", or detailed object | varies |
vertical_axis | string | "Y", "Z" | "Y" |
precision | string | "fixed", "exponential" | "fixed" |
precision_values | integer | 1โ15 | โ |
evaluation_points | integer | 3โ50 | โ |
solver_timeout | integer | seconds | โ |
non_linear_tolerance | string | e.g. "1" (= 1%) | โ |
non_linear_theory | string | "small", "finite" | "small" |
auto_stabilize_model | boolean | โ | false |
member_offsets_axis | string | "global", "local" | "local" |
dynamic_modes | integer | positive integer | 5 |
Detailed units object:
Imperial defaults: ft, in, ksi, lb/ft3, kip, kip-ft, ksf, kip, in, ksi.
nodes#
members#
| Key | Type | Description |
|---|---|---|
type | string | "normal" (default), "normal_continuous", "cable", "tension", "compression", "rigid" โ see below |
node_A | integer | Start node ID |
node_B | integer | End node ID |
section_id | integer | Section ID. null when type = "rigid". |
rotation_angle | float | Rotation about member axis in degrees (โ180 to 180). Ignored for "cable"/"rigid". |
fixity_A / fixity_B | string | 6-character restraint code. Ignored (forced "FFFRRR") for "cable"; still applies for "rigid" and controls which forces/moments transfer through the link. |
offset_Ax/Ay/Az | float | Local offsets at node A. Ignored for "cable"/"rigid". |
offset_Bx/By/Bz | float | Local offsets at node B. Ignored for "cable"/"rigid". |
local_axis_y | [float] | Global vector [X,Y,Z] for local y-axis |
local_axis_z | [float] | Global vector [X,Y,Z] for local z-axis |
mirror | string (optional) | "no" (default), "y", "z", "y_and_z" โ mirrors the member's section about its local axes without needing a separate mirrored section |
disable_non_linear_effects | string (optional) | "yes", "no" (default) โ excludes this member from non-linear/P-delta effects |
type values:
cableโ tension-only, no bending stiffness, true catenary sag. Triggers a non-linear analysis. Forcesrotation_angleโ0,fixity_A/fixity_BโFFFRRR, offsetsโ0.tension/compressionโ linear, single-direction-only axial member (no sag).fixity/offset/rotation_anglebehave asnormal. Prefer this overcableunless true sag matters โ it's simpler and doesn't force a non-linear solve.rigidโ infinitely stiff link,section_id: null, offsets/rotation_angleignored,fixity_A/fixity_Bstill control force/moment transfer.
plates#
| Key | Type | Description |
|---|---|---|
nodes | [integer] | Node IDs forming the plate (min 3, sequential order) |
thickness | float | Plate thickness (section_length units) |
material_id | integer | Material ID |
rotZ | float | Rotation about local Z in degrees (default 0) |
type | string | "auto" โ considers shear deformation automatically |
diaphragm | string | "no" or "rigid" |
state | string | "stress" or "strain" |
meshed_plates#
Manually defined mesh elements (usually auto-generated by S3D.model.mesh).
| Key | Description |
|---|---|
node_A/B/C/D | Corner node IDs. node_D: null for triangular elements |
parent_plate | ID of the parent plate |
sections#
Sections can be defined four ways:
1. Library section (recommended for standard shapes):
2. Custom section from My Sections:
3. Numeric properties only (no design/stress support):
4. Template shape:
Available template shapes: rectangle, hollow rectangle, circle, hollow circle, ibeam/i, tbeam/tee/t, lbeam/angle/l, channel/c, lipped channel, zshape/z, lipped zshape, lipped angle, lipped channel box.
materials#
| Key | Type | Description |
|---|---|---|
name | string | Material name |
density | float | Density |
elasticity_modulus | float | Young's modulus |
poissons_ratio | float | Poisson's ratio |
yield_strength | float | Yield strength |
ultimate_strength | float | Ultimate strength |
class | string | "steel", "aluminium", "concrete", "wood", "masonry", "other" |
supports#
| Key | Description |
|---|---|
node | Node ID |
restraint_code | 6-char restraint code |
tx/ty/tz/rx/ry/rz | Spring stiffness values (used when restraint char = S) |
point_loads#
| Key | Description |
|---|---|
type | "n" (nodal) or "m" (member) |
node | Node ID (when type = "n") |
member | Member ID (when type = "m") |
position | Position along member as % (0โ100, when type = "m") |
x_mag/y_mag/z_mag | Load magnitudes |
load_group | Load group name (string) |
moments#
Same structure as point_loads โ x_mag/y_mag/z_mag represent moment magnitudes about each axis.
distributed_loads#
| Key | Description |
|---|---|
member | Member ID |
x/y/z_mag_A | Load magnitude at start (position A) |
x/y/z_mag_B | Load magnitude at end (position B) |
position_A/B | Start/end positions as percentage (0โ100) |
load_group | Load group name |
axes | "global", "global_projected", or "local" |
pressures#
Applied to plates.
| Key | Description |
|---|---|
plate_id | Plate ID |
x/y/z_mag | Pressure magnitude |
axes | "global", "global_projected", "local" |
load_group | Load group name |
area_loads#
| Key | Description |
|---|---|
type | "one_way", "two_way", "general_one_way", "column_wind_load", "open_structure", "non_rectangular" |
nodes | Node IDs defining the area (3 or 4). Array of integers, except for general_one_way which uses a comma-separated string. |
mag | Load magnitude. Not used for general_one_way โ use mags instead. |
mags | Comma-separated magnitude(s). Required for column_wind_load (paired with elevations) and general_one_way (a single value for uniform, or n values paired with n + 1 values in intervals for a stepped/tapered load) |
column_direction | Span direction as "nodeA,nodeB". Relevant for one_way, column_wind_load, general_one_way |
loaded_members_axis | "all" or "major". Relevant for open_structure and general_one_way |
intervals | general_one_way only โ comma-separated step-interval distances, n + 1 values matching n values in mags. Blank = uniform load |
excluded_member_ids | general_one_way only โ comma-separated member IDs to exclude from carrying the load |
exclude_internal_members | general_one_way only โ "off", "angled", or "all": auto-excludes internal members not aligned to the span |
cantilever_extensions | general_one_way only โ "left,right" offsets extending the load polygon along the span to pick up cantilevered members |
direction | "X", "Y", "Z", or projected variants |
LG | Load group |
Prefer
general_one_wayover plainone_wayโ it's the most robust one-way option: non-rectangular spans, stepped/tapered magnitudes, and finer control over which members carry the load.
self_weight#
load_combinations#
criteria is optional: "strength", "serviceability", or "other". Load group names used as keys (e.g. "Dead", "SW1") โ values are load factors.
load_cases#
Maps load groups to standard load type categories for a named design code. This tells the solver how to classify each load group when auto-generating code-based load combinations.
The key is the design code identifier. Each nested key is a load group name from your model; the value is the code-defined load type for that group.
ASCE 7-22 (LRFD):
AS 1170.0-2002:
EN 1990-2002:
Multiple load groups can map to the same load type (e.g. several wind direction groups all mapped to
"W"). Multiple design codes can coexist in the sameload_casesobject.
groups#
type accepts: "elements", "nodes", "supports", "plates", "groups".
gridlines_and_elevations#
Optional, purely visual/organisational โ doesn't affect analysis, but enables per-level platform features (e.g. isolating a floor). An array (not an integer-keyed dictionary) of elevation/story objects:
axisshould matchsettings.vertical_axis.columns[].s3d_idis the ID of the matching column inmembers/nodes;columns[].section_idis the ID insections.beams,plates,pointsare reserved (mirrorcolumnsstructurally) โ not yet documented, leave as[].gridlines[].grid_idis the label text printed on the gridline;grid_label("start"or"end") controls which end it's printed at.startpt/endptextend slightly paststart_x/start_z/end_x/end_zto leave room for the label โ not the structural extents.
Restraint Codes#
A 6-character string. First 3 = translational DOF (local X, Y, Z). Last 3 = rotational DOF (local X, Y, Z).
| Character | Meaning |
|---|---|
F | Fixed |
R | Released (free) |
S | Spring |
Examples:
"FFFFFF"โ fully fixed (pin/fixed support)"FFFRRR"โ pinned (fixed translation, free rotation)"FFFFFR"โ fixed except rotation about local Z
S3D.model Functions#
S3D.model.set#
Sets the structural model for the session.
S3D.model.get#
Returns the current s3d_model object. Requires S3D.model.set earlier in session.
S3D.model.repair#
Fixes common model issues before solving. Requires S3D.model.set.
| Check | Description |
|---|---|
unused_nodes | Remove floating/disconnected nodes |
large_structure | Detect unit-system issues (extreme slenderness) |
merge_nodes | Merge near-coincident nodes |
zero_members | Remove zero-length members |
continuous_to_normal_members | Split members with intermediate nodes |
intersect_members | Connect crossing members |
default_section | Add a default section to members with none |
force_plate_mesh | Allow analysis without pre-meshed plates |
Omit checks to run all repairs.
S3D.model.solve#
Runs structural analysis. Requires S3D.model.set.
| Key | Type | Default | Description |
|---|---|---|---|
analysis_type | string | "linear" | "linear", "nonlinear", "buckling", "dynamic", "response_spectrum" |
repair_model | boolean | false | Run repair before solving |
return_data | boolean | true | Include solve data in response |
format | string | "json" | "json", "csv", "summary", "s3d" |
lc_filter | [string] | all | "envelope", "envelope_abs_max", "load_case", "load_group", "load_combo", or specific LC names like "LC1" |
result_filter | [string] | all | "reactions", "member_forces", "member_stresses", "member_peak_results", "member_discontinuities", "member_displacements", "plate_forces", "plate_stresses", "plate_element_forces", "plate_element_stresses", "plate_peak_results", "buckling", "dynamic_frequency" |
include_nodal_displacements | boolean | false | Include nodal displacements per load combo |
Tip: Always use
result_filterandlc_filterto minimise response size.
Results are returned as a dictionary keyed by load combination index.
S3D.model.mesh#
Meshes plates. Requires S3D.model.set.
| Key | Type | Default | Description |
|---|---|---|---|
method | string | "frontal_quads" | "frontal_quads", "frontal", "adapt", "packing_parallelograms", "delaunay" |
granularity | integer | 1 | 1 (coarse) to 5 (fine) |
plate_ids | [integer] | all plates | Specific plates to mesh |
S3D.model.takeScreenshot#
Returns base64 PNG screenshots.
| Key | Type | Description |
|---|---|---|
views | [string] | "iso", "front", "side", "top", "custom" |
is_renderer | boolean | Use 3D renderer (true) or wireframe (false) |
wireframe_settings | object | show_nodes, show_loads, show_plates, projection |
zoom_factor | float | โ50 to 50 |
scale | float | 0 to 5 |
S3D.model.surfaceSpringSupports#
Simulates surface spring supports on a plate.
spring_type: "linear", "compression", "tension".
S3D.model.script#
Run custom JavaScript against the S3D model. Useful for complex topology operations.
Write to API_RETURN_DATA to return data. Available S3D functions include S3D.structure.nodes.add, S3D.structure.members.add, S3D.structure.supports.add, S3D.structure.members.intersect, S3D.UI.update.
S3D.model.getLocalAxisVectors#
Returns local axis vectors {x, y, z} for each member.
S3D.results Functions#
S3D.results.get#
Fetches analysis results after solving. Same filter options as S3D.model.solve.
S3D.results.set#
Set results from an external source for further processing.
S3D.results.fetchMemberResult#
Get detailed results for a specific member.
| Key | Type | Description |
|---|---|---|
member_id | integer | Member ID (null = all members) |
LC | [integer] | Load combination IDs (empty = all) |
res_key | string | "bmd_z", "bmd_y", "axial", "sfd_y", "sfd_z", "top_bending_stress_z", "displacement", "displacement_x/y/z" |
type | string | "array", "x,y" (with x positions), "image" (base64 plot) |
S3D.results.getAnalysisReport#
Generate a PDF or TXT analysis report. Requires S3D.model.set and S3D.model.solve.
Returns view_link and download_link URLs.
S3D.results.getDynamicFreq#
Returns dynamic/frequency analysis results.
S3D.file Functions#
S3D.file.save#
Save the current model to cloud storage. Requires S3D.model.set.
Returns a URL to open the file in S3D, and optionally a public_link.
S3D.file.open#
Load a model from cloud storage (sets it for the session).
Use uid instead of name/path if the file UID is known.
S3D.file.share#
Share a model file with other SkyCiv users.
S3D.file.getFileDirectory#
List files/folders in cloud storage.
S3D.file.restoreVersion#
Roll back to a prior version.
S3D.SB (Section Builder) Functions#
S3D.SB.getLibraryTree#
List available sections in the section library.
S3D.SB.loadLibraryShape#
Load a specific section from the library into the session.
S3D.SB.buildCustomShape#
Build a custom section from points or a line-with-thickness.
type: "line" takes an open polyline + thickness to create thin-walled sections.
S3D.SB.solve#
Calculate section properties for the currently loaded section.
S3D.SB.submit#
Submit the current section into the structural model.
S3D.SB.runGSD#
General Section Designer โ FEA-based RC section capacity check.
| Key | Description |
|---|---|
design_code | "ACI", "AS 3600", "BS", "CSA", "EN", "IS 456", "NSCP 2015" |
concrete_class | e.g. "C5000" (ACI) or "N32" (AS) |
steel_grade | e.g. "Grade 60" (ACI) |
reinforcement | Array of {z, y, diam} |
loads | Array of {N, M_z, M_y} |