# Backgrounds

Opposed to characters, backgrounds are actors used to represent a back layer of the scene: locations, sceneries, landscapes or anything that should always appear behind the characters.

A background actor is defined with a name, appearance, visibility and transform (position, rotation, scale). It can change appearance, visibility and transform over time.

Backgrounds' behavior can be configured using Naninovel -> Configuration -> Backgrounds context menu; for available options see configuration guide. The backgrounds' resources manager can be accessed using Naninovel -> Resources -> Backgrounds context menu.

In case you have a lot of backgrounds and it's inconvenient to assign them via editor menu, it's possible to just drop them at Resources/Naninovel/Backgrounds folder, grouped under folders corresponding to actor ID. Eg, to add appearances for a background actor with "MainBackground" ID, store the textures (sprites) at Resources/Naninovel/Backgrounds/MainBackground folder and they'll automatically be available in the scripts.

You can additionally organize appearance resources with sub-folders, if you wish; in this case use forward slashes (/) when referencing them in naninovel scripts. Eg, appearance texture stored as Resources/Naninovel/Backgrounds/MainBackground/Events/CG251 can be referenced in scripts as Events/CG251.

It's also possible to use addressable asset system to manually expose the resources. To expose an asset, assign address equal to the path you'd use to expose it via the method described above, except omit the "Resources/" part. Eg, to expose a "Beach" appearance for "MainBackground" background, assign the texture asset following address: Naninovel/Backgrounds/MainBackground/Beach. Be aware, that addressable provider is not used in editor by default; you can allow it by enabling Enable Addressable In Editor property in resource provider configuration menu.

In naninovel scripts, backgrounds are mostly controlled with @back command:

; Set `River` as the appearance of the main background
@back River

; Same as above, but also use a `RadialBlur` transition effect
@back River.RadialBlur

Backgrounds are handled a bit differently from characters to better accommodate traditional VN game flow. Most of the time you'll probably have a single background actor on scene, which will constantly transition to different appearances. To remove the hassle of repeating same actor ID in scripts, it's possible to provide only the background appearance and transition type (optional) as a nameless parameter assuming MainBackground actor should be affected. When this is not the case, ID of the background actor can be explicitly provided via the id parameter:

; Given a `CityVideo` background actor with `Night` and `Day` appearances (video clips)

; Show the video background playing day clip
@back Day id:CityVideo

; Transition to night clip with ripple effect
@back Night.Ripple id:CityVideo

; Hide the video background
@hide CityVideo

Main background actor record is created by default in the background resources manager and can't be renamed or deleted; however, parameters of the main background (implementation, pivot, PPU, etc) can be freely changed.

# Poses

Each background has Poses property allowing to specify named states (poses).

Pose name can be used as appearance in @back command to apply all the parameters specified in the pose state at once, instead of specifying them individually via the command parameters.

; Given `Day` pose is defined for main background, 
; applies all the parameters specified in the pose state.
@back Day

; Same as above, but for a background actor with `City` ID
; and using `DropFade` transition over 3 seconds.
@back Day id:City transition:DropFade time:3

Notice, that when a pose is used as appearance, you can still override individual parameters, eg:

; Given `Day` pose is defined for main background,
; applies all the parameters specified in the pose state,
; except tint, which is overridden in the command.
@back Day tint:#ff45cb

# Sprite Backgrounds

Sprite implementation of the background actors is the most common and simple one; it uses a single sprite asset to represent appearance of the background. The source of the sprite could be a .jpg, .png, .tiff, .psd or any other image (texture) file format supported by Unity.


Choose file formats that are most comfortable for your development workflow. When building the project, Unity will automatically convert all the source resources (textures, audio, video, etc) to the formats most suitable for the target platform, so it won't make difference in which format you originally store the resources in the project. Find more information on how Unity manage project assets in the official documentation.

# Video Backgrounds

Video backgrounds use video clip assets to represent the appearance.

Video backgrounds can only be managed by editor GUI.

For the supported video formats for each platform see Unity docs for video sources.

For the reference, here is the detailed video parameters of the background video clip that is used in our WebGL demo:

Container : MPEG-4
Container profile : Base Media
Container codec ID : isom (isom/iso2/avc1/mp41)
Format : AVC
Format/Info : Advanced Video Codec
Format profile : High@L4
Format settings, CABAC : Yes
Format settings, RefFrames : 4 frames
Codec ID : avc1
Codec ID/Info : Advanced Video Coding
Bit rate : 3 196 kb/s
Width : 1 920 pixels
Height : 1 080 pixels
Display aspect ratio : 16:9
Frame rate mode : Constant
Frame rate : 25.000 FPS
Color space : YUV
Chroma subsampling : 4:2:0
Bit depth : 8 bits
Scan type : Progressive
Writing library : x264 core 148 r2795 aaa9aa8
Encoding settings : cabac=1 / ref=3 / deblock=1:0:0 / analyse=0x3:0x113 / me=hex / subme=7 / psy=1 / psy_rd=1.00:0.00 / mixed_ref=1 / me_range=16 / chroma_me=1 / trellis=1 / 8x8dct=1 / cqm=0 / deadzone=21,11 / fast_pskip=1 / chroma_qp_offset=-2 / threads=12 / lookahead_threads=2 / sliced_threads=0 / nr=0 / decimate=1 / interlaced=0 / bluray_compat=0 / constrained_intra=0 / bframes=3 / b_pyramid=2 / b_adapt=1 / b_bias=0 / direct=1 / weightb=1 / open_gop=0 / weightp=2 / keyint=250 / keyint_min=25 / scenecut=40 / intra_refresh=0 / rc_lookahead=40 / rc=crf / mbtree=1 / crf=23.0 / qcomp=0.60 / qpmin=0 / qpmax=69 / qpstep=4 / ip_ratio=1.40 / aq=1:1.00

And here is the Unity import settings for this video clip:

Depending on the target platform, it could be required to enable the transcoding in the video clip import settings.


In case having issues with achieving a seamless loop, make sure the video has exactly same starting and finishing frames and a compatible encoding setup; check our video loop example project for the reference.

Be aware, that on WebGL video player can only work in the streaming mode, so all the video resources will be copied to Assets/StreamingAssets/Backgrounds folder upon building the WebGL player. StreamingAssets folder will also appear in the build output directory; make sure to preserve it when publishing the build and check that your web server allows reading the data from this folder.

# Layered Backgrounds

The layered implementation allows composing backgrounds from multiple sprites (layers) and then toggle them individually via naninovel scripts at runtime.

To create a layered background prefab, use Create -> Naninovel -> Background -> Layered asset context menu. Enter prefab editing mode to compose the layers. Several layers and groups will be created by default. You can use them or delete and add your own.

The layered backgrounds are very similar to layered characters; consult the documentation for more info on how to setup and control them via naninovel scripts.

Don't forget that nameless parameter in @back command is expecting appearance and transition type (not ID and appearance as with @char command), so specify layer composition expressions in the following way:

; Given "LayeredForest" background actor
@back Group>Layer,Other/Group+Layer,-RootLayer.TransitionType id:LayeredForest

# Generic Backgrounds

Generic background is the most flexible background actor implementation. It's based on a prefab with a BackgroundActorBehaviour component attached to the root object. Appearance changes and all the other background parameters are routed as Unity events allowing to implement the behavior of the underlying object in any way you wish.

To create generic background prefab from a template, use Create -> Naninovel -> Background -> Generic context asset menu.

Generic backgrounds are very similar to generic characters; check out a tutorial video on setting an animated 3D model as a generic character for one of the possible usage examples.

# Scene Backgrounds

You can use a Unity scene as a background with scene backgrounds implementation.

Scene backgrounds can only be managed by editor GUI; scene assets should be stored under Assets/Scenes project folder.

First, create a new (or move an existing) scene inside Assets/Scenes folder and make sure it has at least one camera. Upon loading scene background, Naninovel will assign a render texture to the first found camera in the scene. The render texture will then be assigned to a background sprite, representing the scene background inside Naninovel scene space. This way, the scene background will be able to co-exist with other background and character actors, support all the background transition effects and scale to handle various display aspect ratios.

Make sure to position the scene objects in world space so that they don't overlap with objects from other scenes, that could potentially be loaded at the same time (eg, when referenced in a single naninovel script). Additionally, be aware, that in case a scene background object is positioned near the global space origin (x0 y0 z0), it could be rendered by Naninovel's main camera; to prevent this, either offset all the scene objects from the global origin, or use Configuration -> Engine -> Override Objects Layer to isolate Naninovel-related objects using layers.

After scene setup is complete, create a new background actor via Naninovel -> Configuration -> Backgrounds menu, select SceneBackground implementation and add the scene asset to the actor resources.

When assigning resources for a scene background actor, corresponding scene assets should automatically be added to the build settings; in case you're getting an error that a scene asset wasn't added to the build, try adding it manually.

You can now use @back command to control the created scene background actor, eg:

@back SceneName id:ActorId
Last Updated: August 31, 2020