An EXILED plugin for SCP: Secret Laboratory that renders 3D meshes from OBJ files in the game world using Unity primitive toys (Quads, Spheres, Cylinders, Cubes).

• Plugin: TriangleScpSl v5.0.0
• Author: Foibos
• Framework: net48 / EXILED 9.13.3
• License: CC-BY-SA 3.0 (required by EXILED)

1. Build the project or grab the latest release.
2. Copy TriangleScpSl.dll into EXILED/Plugins/.
3. Place your .obj (and optional .mtl) files in EXILED/Plugins/BlenderModels/.
4. In Remote Admin, run the command to display or export your model.

The plugin converts OBJ mesh faces into Unity primitives that can be spawned in SCP:SL.

Any convex polygon can be decomposed into parallelograms. A parallelogram can be rendered using Unity Quads by exploiting the SetParent deformation trick: a child primitive inherits the non-uniform scale of its invisible parent, producing a sheared shape.

The plugin applies several tricks to minimize the number of primitives needed:

V1 (Exact): Each parallelogram = 2 Quads (base + visible child). Pixel-perfect.

V2 (Approximate): Groups parallelograms by angular similarity under shared "stretch" primitives. Fewer total primitives at the cost of tiny vertex error (configurable accuracy parameter).

TriangulateNGonV2 - the recommended display command

This command applies the N-gon pipeline with V2 stretch clustering. Adjust optimization parameters (hidden tails, primitive detection, planar threshold, etc.) via NGonConfig.

TriangulateNGonV2 <model.obj> [planar threshold] [accuracy]

For export, use ExportSchematicNGonV2 with the same pipeline.

Every command can be run again while building to cancel, or run again after the model is visible to destroy it.

The NGon pipeline is configured through NGonModelConfig, a session-scoped config that persists until the server restarts. Use the NGonConfig RA command to view and change values at runtime. All subsequent NGon commands (TriangulateNGon, TriangulateNGonV2, and their export variants) will use the updated defaults.

NGonConfig                          -- list all current values
NGonConfig PlanarThreshold          -- get a single value
NGonConfig PlanarThreshold 0.01     -- set a value for this session

To reduce primitive count (at the cost of accuracy):

• Enable UseHiddenTailOptimization and DetectPrimitives if disabled
• Increase Accuracy (e.g. 0.01) to allow more stretch reuse
• Increase HiddenTailPullIn (e.g. 0.1) to get less primitives at the cost of more visible spikes on the model
• Increase PlanarThreshold (e.g. 0.0001 - 0.001) to merge more coplanar faces (not that much of optimization)
• Increase SmoothMaxAngle (e.g. 0.5) for more aggressive shape detection
• Enable AllowNonPlanarNGons to keep large n-gons intact instead of splitting them (may cause heavy geometric inaccuracy)

To increase visual accuracy (at the cost of more primitives):

• Set PlanarThreshold to 0
• Enable UseEdgeWalkSampling for hidden tail optimization to catch small pits and holes in the model (warning: very slow)
• Decrease Accuracy (e.g. 0.0001 - should be enough for any model)
• Decrease SmoothMaxAngle to avoid replacing low-poly geometry with smooth shapes

To speed up loading (at the cost of gameplay smoothness):

• Increase MaxMsPerFrame (e.g. 16 or 32)

Each subfolder with significant logic has its own README.md with detailed algorithm descriptions.

TriangleScpSl/
  Plugin.cs, Config.cs          - EXILED plugin entry point
  Commands/                     - Remote Admin commands
  Core/
    FileToTriangles/            - Simple OBJ parser (triangle-based, legacy)
    ModelFactory/               - Factory for loading OBJ and creating models
    Models/
      ModelBase.cs              - Abstract base with shared fields and methods
      ApproximateModel/         - V2 stretch-clustering renderer
      ExactModel/               - V1 exact parallelogram renderer
    NGons/                      - N-gon decomposition pipeline
      Detectors/                - Primitive shape detection
    Triangulation/
      Triangle/                 - Triangle data and decomposition into parallelograms
      Parallelogram/            - Parallelogram data and the 2-Quad shearing primitive
    ProjectMerExport/           - ProjectMER schematic JSON export
    Paths/                      - File path utilities
    Runtime/                    - Coroutine host

For programmatic use, the key entry points are:

// Load an OBJ with the full N-gon pipeline (recommended, coroutine)
NGonModelConfig config = NGonModelConfig.CreateFromSession();
yield return NGonModelBuilder.LoadCoroutine("model.obj", Color.white, result =>
{
    // result.Parallelograms, result.DetectedPrimitives, result.NormalizedFileName
}, config);

// Or synchronous (blocks the main thread)
NGonModelResult result = NGonModelBuilder.Load("model.obj", Color.white, config);

// Create models
var exact = ExactModel.Create(result.Parallelograms, result.DetectedPrimitives, position);
var approx = ApproximateModel.Create(result.Parallelograms, result.DetectedPrimitives, position);

// Or deferred (build in coroutine to avoid lag)
var model = ApproximateModel.CreateDeferred(result.Parallelograms, result.DetectedPrimitives, position);
yield return model.BuildTrianglesCoroutine(PrimitiveFlags.Visible, batchSize: 64);

// Control
model.Position = newPos;
model.Rotation = newRot;
model.Scale = Vector3.one * 2f;
model.Color = Color.red;
model.Destroy();

See Core/Models/ApproximateModel/README.md and Core/Models/ExactModel/README.md for full API details.

• EXILED — Creative Commons Attribution-ShareAlike 3.0 Unported
• Mirror Networking — MIT
• Unity Engine — Unity Companion License