# Creating Sector Variants

## Summary

Published: Mar 18 2025 by [keanuWheeze](https://app.gitbook.com/u/WBUIHettvKP7ke8K6KFd7L9ZTtG2 "mention")\
Last documented edit: Mar 22 2026 by [mana vortex](https://app.gitbook.com/u/NfZBoxGegfUqB33J9HXuCs6PVaC3 "mention")

This page walks you through creating sector variants with WorldBuilder

### Wait, that's not what I want!

* For an example, check [sector-variants-practical-example-and-project](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/world-editing/object-spawner/features-and-guides/creating-sector-variants/sector-variants-practical-example-and-project "mention")
* For how to manually create sector variants, check [Switching between sector states](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/world-editing/archived-guides/switching-between-sector-states) (archived)

## Why do I need sector variants?

This feature allows **switching** between multiple versions of the same build **while the game is running**, for example

* turning Johnny or Nibbles on and off
* "Moving" smartframes around
* Having multiple presets, for example light colours and -brightness
* turning an entire build on and off (great for non-immersive mods and shenanigans)

Variants allows you to make all sorts of World Edits - imagination is your sole limit.

{% hint style="info" %}
Despite the name, you can have as many variants in a single .archive as you want.
{% endhint %}

## Requirements

### Tools

* WorldBuilder ([github](https://github.com/justarandomguyintheinternet/CP77_entSpawner/releases) | [Nexus](https://www.nexusmods.com/cyberpunk2077/mods/20660))
* [ArchiveXL](https://github.com/psiberx/cp2077-archive-xl)
* [Codeware ](https://github.com/psiberx/cp2077-codeware/releases)(1.15.0 or newer)
* [WolvenKit](https://github.com/WolvenKit/WolvenKit) ([Stable](https://github.com/WolvenKit/WolvenKit/releases) | [Nightly](https://github.com/WolvenKit/WolvenKit-nightly-releases/releases))
* The latest version of World Builder import script (Wolvenkit will update scripts during start)

### Knowledge

* You need to have a basic understanding of:
  * Working with WolvenKit
  * Using World Builder (Spawning things and [importing](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/world-editing/object-spawner/exporting-from-object-spawner) into WolvenKit)

## General Setup

If you want to use variants, keep them in mind during the building process — group things that belong together.

* You will be able to assign each group, which sits directly within the main group, to a variant

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-e8fff1503ce4473d3d773bf636fb00e91dbbe1b7%2FsectorVariantValidGroupsExample?alt=media" alt="" width="248"><figcaption><p>Example of what groups will be assignable</p></figcaption></figure>

* In the above example, you will be able to assign each of the three groups to a variant
  * All objects placed directly within the root group (The group that you saved and export), will be part of the **default** variant

## Assigning variants

* Once you have added your group(s) to the export, you can start assigning variants
* Variant settings can be found under the equally named header (One per group)
* By default, each group will be assigned to the `default` variant, meaning they will be always active

<figure><img src="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-78c65e9d25e759d3e60a2de8b5581393228185c2%2FsectorVariantExample?alt=media" alt=""><figcaption><p>Example of a variants setup for a group, in the export tab</p></figcaption></figure>

* Variant Node Ref:
  * This **MUST** be set to an unique NodeRef in order for the variants to be controllable
* Below you can assign a variant to each group
  * You can assign multiple groups to the same variant
  * Optionally change whether the variant should be active by default

## Testing variants

* In order to quickly toggle variants on and off, during development and testing, you can use the following commands in the CET-Console:

```lua
Game.GetWorldStateSystem():TogglePrefabVariant(CreateNodeRef("$/yourRefName"), "variantName", true) -- Toggle variant on
Game.GetWorldStateSystem():TogglePrefabVariant(CreateNodeRef("$/yourRefName"), "variantName", false) -- Toggle Variant off
```

## User Configurable Variants

* In order for mod users to quickly and conveniently toggle variants, one could e.g. hook up the [above](#testing-variants) code to some UI
* To make it easier, below there will be a ready to use Native Settings UI based menu, that allows toggling variants
* In order to configure it, simply change the values at the top of the `init.lua` file:
  * `settingsMainName/settingsSubName` : Controls the names displayed for the category, in Native Settings UI
  * `defaultMutuallyExclusiveVariants`: Here you define string selectors for variants which should be mutually exclusive (Only one active at a time)
    * `ref`: This is the variant node ref
    * `displayName`: This is a more human-readable string, gets actually shown in the UI
    * `currentIndex`: This is the default state (Will override what is defined during export)
    * `variants`: This array contains the variants which should be mutually exclusive, with a display name
  * `defaultAdditiveVariants`: Here you define simple switches for variants which can be mixed and matched
    * `ref`: This is the variant node ref
    * `variant`: The name of the variant, as defined during export
    * `displayName`: This is a more human-readable string, gets actually shown in the UI
    * `defaultState`: The default state of the variant (Overrides what is set during export)

{% file src="<https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2FbrmJff0mQxRmEs9RnvyH%2FVariantSwitcherUpdated.rar?alt=media&token=ccdf44ca-abb0-459e-83b7-ef40b6a4f075>" %}

## Practical example and project template

You can find more documentation and a project template with WB saves/export template/export files included in it to visualize how it all works in game and on wolvenkit at the following page :\
[sector-variants-practical-example-and-project](https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/world-editing/object-spawner/features-and-guides/creating-sector-variants/sector-variants-practical-example-and-project "mention")


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.redmodding.org/cyberpunk-2077-modding/modding-guides/world-editing/object-spawner/features-and-guides/creating-sector-variants.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.