Source content guidelines

Audience: modelers preparing model groups that the Alpha configurator will merge into a configured house.

Why this document exists

The configurator combines per-group RVT files into one configured house RVT by calling Revit's CopyElements API across documents. When source files share certain content patterns, Revit's internal element-id mapping can't reconcile them and the copy aborts with a low-level m_big2SmallMap2 assertion. The result: some of your groups silently fail to land in the configured output.

This is behavior inside Revit's native code; we can't fix it from the addin. But the failure has a clear content fingerprint, and adjusting how groups are modeled stops triggering it.

Below: what we observe, what we believe causes it, what to check on each source RVT, and the modeling rules that prevent it.

What we observe

In a recent run with 17 source RVTs (all from one tenant, all derived from the same configuration template):

• Each source copies cleanly into a fresh blank target on its own.
• When merged sequentially into one shared target (the actual configurator workflow), 7 of 17 abort with m_big2SmallMap2.
• Switching the order of the 17 sources changes which 7 fail but the count stays at 7. Failures are pair-specific, not order-based.
• Stripping unused element types from each source first (Purge Unused-style) does not change the result.

That last point is the key diagnostic: the conflicting elements are actively referenced by the group, not unused leftovers. So the fix is not "purge harder"; it's "stop modeling the group in ways that leak shared dependencies across files."

Likely culprits, in order of probability

When you open a failing source in Revit, work through this checklist. The first hit is almost always your fix.

1. Reference Planes inside the model group

Reference Planes are notorious for being silently referenced by other elements (constraints, alignments, families that were placed against them). They survive copy and they often persist invisibly. Two source files that both contain a Reference Plane with the same name are guaranteed to collide during merge.

Check: Edit Group → look for purple Reference Planes among the members.

Fix: Delete every Reference Plane inside the group. If a constraint depends on one, replace the constraint with a Level reference or rebuild it with a fresh RP that lives outside the group.

2. Face-based or work-plane-hosted families inside the group

If a face-based family is hosted on a wall in another group (or on a wall that CopyElements will duplicate), its host reference becomes ambiguous when the host is copied. The walker tries to map the host two ways and aborts.

Check: select each FamilyInstance in the group → Properties panel → look at "Host". If the host is a wall, floor, ceiling, or face, verify the host is also inside the same group. If the host lives elsewhere, that's the trigger.

Fix: prefer level-based or unhosted families for any element that crosses group boundaries. If a face-based family is unavoidable, ensure its host is inside the same group as the family.

3. Schedules and view filters in the source RVT

A schedule with a category-wide rule (e.g., "all walls where Type Mark = X") creates a project-wide dependency that flows through CopyElements. The schedule has no purpose in a fragment used by the configurator; it just adds dependency surface.

Check: Project Browser → expand "Schedules/Quantities". Anything in there?

Fix: delete all schedules from source RVTs before export. (The configurator only copies the model group; schedules don't help.)

4. DWG / linked CAD imports inside the group

CAD imports drag in their own line patterns, fill patterns, and text styles. These partially overlap with the template's versions in unpredictable ways and cause exactly the pair-specific collisions we're seeing.

Check: the addin's Health Check has a "DWG/DXF Imports" row; anything other than 0 is a flag.

Fix: explode CAD imports into native Revit linework before saving the source, or replace them with Revit-native model elements. Never leave a CAD import inside a group that the configurator consumes.

5. In-place families

Each in-place family is unique geometry living inside one document. When CopyElements brings it across, it doesn't deduplicate the way loadable families do. Two sources with similarly-named in-place families collide.

Check: Health Check → "In-Place Families" row.

Fix: convert in-place families to loadable families. Or move the geometry into walls/floors/generic models if it doesn't need its own family wrapper.

6. Workshare residue

A source RVT that was ever a workshared central or local carries sync metadata even after Detach from Central. This metadata can survive Save As and conflict during merge.

Check: Manage → Worksets: is the option grayed out / present? If present, the file has worksharing on.

Fix: open with Detach and discard worksets, then Save As, then re-export. Repeat for every source RVT.

7. Shared parameters with project-wide bindings

A shared parameter bound to a category at project scope (rather than just to specific elements in this group) brings the binding along during copy. If two sources have the same parameter bound to overlapping categories with different values, the walker has to reconcile and may not.

Check: Manage → Project Parameters → scan for any with Category bindings. Manage → Shared Parameters → check the parameter file path.

Fix: keep parameter bindings local to the group's elements where possible. Use instance/type parameters on the family rather than project parameters.

Modeling rules going forward

These are the practices to adopt for any RVT that's destined to be a configurator source. They eliminate the failure modes above structurally rather than through inspection.

1. Use the same template for every export, unmodified. Not "the master template" or "a derivative." The same .rte file path, every time. Even small differences (added wall types, renamed line styles, modified default views) become collisions.
2. Run Purge Unused before every export. Reduces the cross-source overlap surface and keeps file sizes sane.
3. No Reference Planes inside groups. Use Levels.
4. Each group is self-hosted. Anything inside the group that's hosted on something else must be hosted on something also inside the group. No cross-group hosting.
5. No schedules in source RVTs. They add nothing for the configurator.
6. No CAD imports inside groups. Explode or replace before export.
7. No in-place families. Convert to loadable families.
8. Detach + discard worksets if the source RVT has any worksharing history.
9. Run Health Check before exporting each source. Use the Copy report button to capture the result. The goal: each source passes Health Check before it goes into the library.

How to verify a source after editing

1. Open the source RVT in Revit.
2. Tools → Health Check → resolve every Warning and Error row.
3. Compare against other sources in the library by re-exporting and checking that the configurator merge no longer drops it.

When in doubt

If a source fails Health Check on a row you don't understand, click Copy report and send the output to the Alpha team. We'll look at it and either tell you what to change or expand the check to be clearer about what it caught.