{"id":"nightcycle/quick-part","name":"quick-part","scope":"nightcycle","platform":"roblox","description":"Batched EditableMesh rendering and cheap rigid model transforms.","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"Apache-2.0","licenseRating":"safe","licenseCaveats":["Modified files must carry a notice of changes. If the package ships a NOTICE file, its attributions must be preserved."],"licenseVerified":true,"dependencies":{},"integrity":"96d0519c01781aa1b223777c76c5ef2cec4a8874c7d6b5ac5a7e3f502a7647fa","likes":0,"downloads":0,"install":"forest install nightcycle/quick-part","url":"https://forest.dev/p/roblox/nightcycle/quick-part","files":"https://api.forest.dev/ai/package/roblox/nightcycle/quick-part/files","readme":"# QuickPart\n\nStrict, native Luau for rendering many visual parts through shared EditableMeshes. Compatible parts share a MeshPart; a block uses eight vertices and twelve triangles. Colour and opacity live on face-corner colour IDs, so changing one handle does not recolour its neighbours. Models use separate batches so rigid movement and uniform scaling only change the hosting MeshParts.\n\nThis follows the `local-package` template's `src` / standalone Rojo project / demo Rojo project / Rokit / Wally layout. No runtime dependencies. Prepared as `nightcycle/quick-part@0.1.0`; **not published**.\n\n## Build and try it\n\n```sh\nrokit install\nlune run scripts/check\nlune run scripts/build\nrojo serve demo.project.json\n```\n\n`check` runs the Lune sandbox, release validation tests, StyLua and Roblox strict type analysis. It caches pinned upstream luau-lsp Roblox definitions in `.tools/`; for offline checking, pass an existing definitions file: `lune run scripts/check path/to/globalTypes.d.luau`. `build` deserializes the artifacts to verify their structure and compiles every embedded script:\n\n- `build/quick-part-demo.rbxl`: includes a spawn point and five labeled, side-by-side comparison rows, visible before Play. Press **Play (F5)** to animate the real BaseParts/models on the left and their QuickPart versions on the right: five primitives changing properties, 100 moving cubes, a rotating/scaling 26-part arch, two birch trees with separate trunks and transparent leaf cards, and a woodland scene with a round tree, pine, bush, ferns, grass and boulder. Walk around with the avatar and normal Roblox camera; **Pause animation** lets you inspect matching poses. The right side is explicitly labeled as a BasePart preview until mesh creation succeeds; if EditableMesh is unavailable, the reference animations continue and the UI reports the failure. Use Play, not the server-only Run mode, for the client animation.\n- `build/quick-part.rbxm`: standalone ModuleScript package.\n- `build/quick-part-<version>.zip`: Wally archive, named from `wally.toml`, containing only package sources, README, license and manifests. Wally 0.3.2 produces ZIP data.\n\nEnable Mesh / Image APIs in the experience's security settings. Mesh imports also require Roblox's asset permissions. Editable assets have client memory limits and may fail to allocate. See [Roblox's EditableMesh documentation](https://create.roblox.com/docs/reference/engine/classes/EditableMesh).\n\nThe foliage comes directly from the supplied `local-package/demo/lib.rbxm`. The selected subset is checked in at `demo/assets/LibrarySamples.rbxm`, with original paths in `provenance.json`; normal builds do not need the template repository. `lune run scripts/extract-library <path-to-lib.rbxm>` refreshes it. Geometry, textures, double-sided leaf cards and SurfaceAppearance are retained; samples are anchored and positioned with a ground-level pivot. Demo assets are excluded from the Wally package.\n\nThese third-party meshes currently render as MeshParts but their EditableMesh imports are denied in the connected Studio session. Roblox requires mesh ownership or explicit sharing for editing; enabling the API alone does not grant that access. Until the assets are shared appropriately (or replaced with editable assets), the new rows show synchronized animated originals and an **Asset access denied** status. They do not claim to be QuickPart output.\n\n## CI and releases\n\nGitHub Actions runs **CI / Check and build** for pull requests, pushes to `main`, and manual runs. It lints workflows, installs the pinned Rokit toolchain, runs `scripts/check` and `scripts/build`, then uploads the package, demo place, and Wally ZIP as artifacts retained for 14 days. Studio integration tests and engine performance benchmarks still run in Studio; CI runs the Lune sandbox checks.\n\nPushing a stable `vX.Y.Z` tag starts **Release**. The workflow verifies that the tag matches `wally.toml` and the checked-out commit, reruns checks/builds, and creates a GitHub release with all three artifacts. Existing release assets can be refreshed by manually running Release for the same tag. Actions are pinned to commits, with weekly Dependabot updates.\n\nTo enable Wally publication, add the repository Actions secret `WALLY_AUTH_TOKEN` containing a Wally registry token. The release workflow publishes to Wally after the GitHub release; if the secret is absent, it explicitly skips Wally publication and records that in the run summary. It checks Wally's success message as well as its exit code because Wally 0.3.2 can exit zero on registry errors. No Roblox/Open Cloud credential is needed for these workflows.\n\nFor a release, update `wally.toml`, commit and push the changes, then create and push the matching tag. For example, after setting the package version to `0.1.1`:\n\n```sh\ngit tag v0.1.1\ngit push origin v0.1.1\n```\n\nThe workflows become available when `.github/workflows` is pushed to GitHub. To require CI before merging, select **Check and build** in the repository's branch rules after its first run.\n\n## Part handles\n\nRequire only the package entry point. It exposes the shared `Renderer`, `CONSTANTS`, `Geometry`, `Mesh`, `Import`, `PartSource`, and `Types` modules; consumers do not require child ModuleScripts. Luau types are re-exported directly from the root, for example `type PartHandle = QuickPart.PartHandle` and `type Renderer = QuickPart.Renderer` (`Types` has no runtime values).\n\nRenderer instances, including the default renderer returned by the package, use colon methods: `renderer:Create(...)`, `renderer:Update(...)`, and `renderer:Destroy()`. Constructors remain `QuickPart.new()` / `QuickPart.Renderer.new()`, and stateless helpers use dots, for example `QuickPart.Geometry.primitive(...)`.\n\n```luau\n--!strict\n--!native\nlocal QuickPart = require(game.ReplicatedStorage.Packages.QuickPart)\nQuickPart.CONSTANTS.TRIANGLE_BUDGET_PERCENT = 70\n\nlocal part, reason = QuickPart:Create({\n    Size = Vector3.new(4, 2, 6),\n    CFrame = CFrame.new(0, 10, 0),\n    PivotOffset = CFrame.new(0, -1, 0),\n    Material = Enum.Material.SmoothPlastic,\n    Reflectance = 0,\n    CastShadow = true,\n    Color = Color3.fromRGB(60, 180, 255),\n    Transparency = 0.2,\n    -- SurfaceAppearance = anExistingSurfaceAppearance,\n})\nif not part then\n    warn(reason)\n    return\nend\n\npart.CFrame = CFrame.new(0, 15, 0)\npart.Size = Vector3.new(6, 2, 6)\nQuickPart:Update(part)\nQuickPart:PivotTo(part, CFrame.new(0, 20, 0))\nQuickPart:Remove(part)\n```\n\nA `PartHandle` has `Id: number` (monotonically increasing integer, treat as read-only), `Size`, `CFrame`, `PivotOffset`, `Color`, and `Transparency`. Mutating a table does nothing until `Update` / `UpdateMany`. Like a BasePart, its pivot is `CFrame * PivotOffset`; changing PivotOffset alone does not move geometry. `PivotTo` computes CFrame from that offset. Size must be positive and transparency in `[0, 1]`.\n\nPrefer `CreateMany(options)` and `UpdateMany(handles)` for populations. Creation prepares all topology before yielding to attach hosts, and a failed creation rolls back the entire call. UpdateMany uses one `BatchSetValues` call per changed mesh when supported, reuses mesh buffers, and skips unchanged geometry. Older engines fall back to SetPosition. Colour-only changes do not write vertices. Concurrent creation/mutation on the same renderer is rejected while an asynchronous creation is in flight.\n\n| API | Result / purpose |\n| --- | --- |\n| `Create(options)` | `PartHandle?, reason?`; default shape is Block |\n| `CreateMany(optionsArray)` | `{PartHandle}?, reason?`; atomic creation |\n| `FromPart(basePart)` | Imports a supported visual BasePart; leaves the source alone |\n| `Update(handle)` / `UpdateMany(handles)` | Applies mutable handle properties synchronously |\n| `GetPivot(handle)` / `PivotTo(handle, pivot)` | BasePart-style pivot operations |\n| `Remove(handle)` / `RemoveMany(handles)` | Removes faces and unused attributes; destroys empty mesh hosts |\n| `GetGeometry(handle)` | EditableMesh, host, and copies of stable vertex, face, triangle, colour and normal IDs |\n| `GetStats()` | Parts, Models, Meshes, Triangles, TriangleLimit and BatchMeshes |\n| `Destroy()` | Disconnects and destroys everything owned by this renderer; idempotent |\n| `new()` | Independent renderer with the same API and shared CONSTANTS |\n\n`GetGeometry` is an inspection/advanced integration escape hatch. Do not remove IDs, destroy its mesh, or edit its host's Size/CFrame behind the renderer. IDs are stable but sparse; never use an ID as an array index. Handles belong to their originating renderer and become invalid after removal or destruction.\n\nCreation options also accept `MaterialVariant`, `Shape` (Block, Wedge, CornerWedge, Ball, Cylinder), `TextureID`, `DoubleSided`, or an explicit normalized `Geometry`. `Geometry.primitive` and `Geometry.transform` expose reusable functions. Treat cached primitive geometry as read-only. Custom geometry uses vertices in size-normalized local space and triangle/quad faces with per-corner UVs, optional normals, colours and alpha; `TriangleCount` must match the actual triangulation.\n\n## Models and rendering root\n\n```luau\nlocal renderer = QuickPart.new()\nlocal model, reason = renderer:FromModel(workspace.MyModel)\nassert(model, reason)\nmodel.WorldPivot = CFrame.new(0, 20, 0) * CFrame.Angles(0, math.pi / 2, 0)\nmodel.Scale *= 2\nrenderer:UpdateModel(model)\nrenderer.RenderingPart.Name = \"Scene visuals\"\nrenderer.RenderingPart.CFrame = CFrame.new(50, 0, 0)\nrenderer:RemoveModel(model)\nrenderer:Destroy()\n```\n\n`FromModel` includes descendant BaseParts and captures the model's pivot and existing scale. `Scale` is absolute, matching `Model:GetScale()`; doubling it doubles the captured geometry. WorldPivot/Scale edits need `UpdateModel`. Models retain internal part records for cleanup but do not expose independently editable part handles. Their transforms cost O(material batches), with no per-vertex writes. Source models remain untouched; hide or remove them yourself after a successful import if replacing their visuals.\n\nEach renderer exposes an invisible, anchored `RenderingPart` in Workspace. Its child MeshParts host the EditableMeshes. Changing the root CFrame applies an additional transform to all batches via a property-change connection, including models. Handle CFrame/WorldPivot values stay in the original coordinate system; rendered transforms are `RenderingPart.CFrame * handleTransform`. Renaming/reparenting the root is supported. Moving it does not rewrite every handle. Root Size is not a scale control. Call `Destroy` instead of manually destroying the root.\n\nBatches are separated by material, material variant, reflectance, CastShadow, texture, DoubleSided, and SurfaceAppearance **instance identity**, plus capacity and model ownership. Sharing the same SurfaceAppearance instance allows batching; it is cloned onto the host. Those settings are captured at creation and are not mutable handle properties.\n\n## Budget and fidelity\n\n`CONSTANTS.TRIANGLE_BUDGET` defaults to 20,000 and `TRIANGLE_BUDGET_PERCENT` to 80, allowing 16,000 live triangles **per renderer**. This is an application allowance: Roblox does not expose remaining device EditableMesh memory or a conversion between triangle count and bytes. The allowance cannot guarantee allocation success. Lowering it blocks new allocations until enough geometry is removed; it does not evict existing handles. Roblox's per-mesh limits are also enforced. `Create*` / `From*` return `nil, reason` on exhaustion, unsupported sources or engine errors. Luau's null value is `nil`. See [AssetService allocation behavior](https://create.roblox.com/docs/reference/engine/classes/AssetService).\n\nThis is a visual renderer: hosts are anchored with collision, touch and query disabled, and collision geometry is not rebuilt on updates. Build client visuals locally; EditableMesh changes are not a network replication protocol. `--!native` is included, but native execution depends on the Roblox execution context.\n\nBlocks and wedges preserve primitive shape. Balls and cylinders are tessellated approximations with smooth normals; `CURVE_SEGMENTS` controls detail for newly created handles. Static MeshParts preserve accessible geometry, normal/UV seams, vertex colours/alpha, TextureID and SurfaceAppearance. Asset decoding may yield and use temporary editable memory. Skinned meshes, CSG/UnionOperation, TrussPart, SpecialMesh and Decal/Texture children are rejected. Other descendants such as lights, particles, attachments and scripts are not imported.\n\nPixel-identical rendering for every Roblox BasePart is not promised: primitive texture mapping, legacy surfaces, transparency sorting, built-in material shading and engine culling can differ from individual parts. Primitive UVs cover each polygon; supply custom geometry/UVs for a specific PBR atlas. Host bounds originate at creation, so validate culling for your movement range in Studio, especially when adding geometry far outside the initial bounds. Prefer creating related populations together and spatially partition large scenes with separate renderers.\n\n## Benchmarks\n\n### Recorded results\n\nStudio results supplied on 2026-10-29 using **Benchmarker v7.3.0**. Each sample updates **1,000 parts once**; setup is excluded. All timings below are milliseconds, transcribed from the screenshots' percentile tables. Hardware and Studio build were not provided.\n\n**Independent1000 — individually moving parts**\n\n| Method | P10 (ms) | Median / P50 (ms) | P90 (ms) | QuickPart median speedup |\n| --- | ---: | ---: | ---: | ---: |\n| **QuickPart UpdateMany** | **0.618** | **0.770** | **1.016** | — |\n| BulkMoveTo FireCFrameChanged | 2.000 | 2.389 | 3.547 | 3.10× |\n| BulkMoveTo FireAllEvents | 5.005 | 5.361 | 6.469 | 6.96× |\n| BasePart CFrame | 5.297 | 5.707 | 6.745 | 7.41× |\n\n**RigidModel1000 — moving 1,000 parts as one model**\n\n| Method | P10 (ms) | Median / P50 (ms) | P90 (ms) | QuickPart median speedup |\n| --- | ---: | ---: | ---: | ---: |\n| **QuickPart UpdateModel** | **0.012** | **0.017** | **0.033** | — |\n| BulkMoveTo FireCFrameChanged | 1.993 | 2.500 | 3.973 | 147.06× |\n| BulkMoveTo FireAllEvents | 4.998 | 5.504 | 6.931 | 323.76× |\n| BasePart CFrame | 5.307 | 5.824 | 7.174 | 342.59× |\n\nSpeedup is the baseline median divided by the QuickPart median, using the displayed rounded values. In these runs, QuickPart took **0.770 ms** for independent movement and **0.017 ms** for rigid model movement, versus **2.389 ms** and **2.500 ms** for the fastest baseline, BulkMoveTo FireCFrameChanged. These are CPU submission timings for these workloads, not whole-frame rendering times.\n\n<details>\n<summary>Original benchmark screenshots</summary>\n\n![Independent1000 benchmark results](docs/benchmarks/independent1000.png)\n\n![RigidModel1000 benchmark results](docs/benchmarks/rigid-model1000.png)\n\n</details>\n\n### Running the benchmarks\n\nThe supplied `Benchmarker (1).rbxm` was deserialized with Lune and its Runner/Template inspected as reference data. Its plugin code is not redistributed. Select one of these modules under `ReplicatedStorage.Benchmarks` in the built place and run the installed Benchmarker plugin in edit mode:\n\n- `Independent100.bench`: 100 independently updated handles.\n- `Independent1000.bench`: 1,000 independently updated handles.\n- `RigidModel1000.bench`: 1,000 parts moving as one rigid model.\n- `LibraryWoodland.bench`: the eight original woodland MeshParts moving as one model.\n- `LibraryFoliage.bench`: those same MeshParts moving through individual handles and UpdateMany.\n\nBoth library benchmarks use one full population update per sample and import real mesh geometry before timing. Asset permission or budget failures abort setup and clean up; they are not reported as performance results. Run them once the mesh assets can be edited by the current experience/user.\n\nEach compares direct `BasePart.CFrame`, `Workspace:BulkMoveTo(..., FireAllEvents)`, `Workspace:BulkMoveTo(..., FireCFrameChang","readmeTruncated":true,"readmeFull":"https://api.forest.dev/v1/package/nightcycle/roblox/quick-part/0.1.0/readme"}