Immersive Environments V2 - Packages
Download
GitHub Repository
Roblox Library Model
Example Place
Key New Features
- Packages support
- Expanded control and flexibility
- Better internal handling for regions
- Minimalist API
- Easier to fork and modify (internally more coherent)
-
CullingService compatibility
What are Packages?
Packages are a collection of lighting or audio settings which correspond to different time periods. If you are familiar with earlier iterations of IE, this should be familiar, as this was how the default server lighting and server audio settings worked. Now though, packages are the universal way for determining lighting settings, meaning it’s possible to have multiple packages in-game and to freely switch between them. In the previous version of IE, there was essentially only a server audio and lighting package, and then region and weather settings applied a static change to the audio or lighting.
Here’s an example of why this behavior was changed
Example
Example scope: Region
Setting: Blacksmith Shop
Audio Package
Previous version of IE (no packages, just a standardized configuration of audio settings):
A player enters a blacksmith shop and a store ambience plays followed by randomized clanging sounds.
That’s cool and does the trick in a lot of circumstances. But this about creating immersive environments and the idea is to supercharge the ability for developers to fine tune their audio and lighting settings and boost the immersive quality of their games.
Current version of IE (packages):
A player enters the blacksmith shop and a store ambience plays followed by randomized clanging sounds. The store ambience rises and falls to different pitches and volumes depending on the time of day. As the day progresses, the sound of the ambience grows and climaxes around mid-day, the busy period. The randomization rates of the clanging increase, too, in order to simulate the audio sensation of more activity. As the shop nears the closing time, randomized sounds of the blacksmith yelling “Last call! Last call!” are played. At night, the ambience fades quietly and disappears.
That is the idea of what IE is supposed to support.
Package support is lent to everything now: server, region, and weather. This means that, rather than relying on server settings, you can actually chop up your entire map into regions, and directly tailor the audio and lighting packages that way. This way, you can fine tune your audio and lighting, if the literal environment conceivably impacts that. For example, the lighting and ambience of a city might be highly different from the lighting and ambience of a plain.
New API and Settings
API
Notes:
- PackageName is the name of whatever your package is (this will be the folder name under Packages)
- PackageType is always either “Audio” or “Lighting”
- All API calls should be done from the server, with the exception of Main:Run() which should be called once from both the server and client
Main:Run()
This runs IE - call this before interacting with anything else in the API
Main:SetServerPackage(PackageType: string, PackageName: string)
This sets the server package.
Main:SetWeatherPackage(PackageType: string, PackageName: string)
This sets the weather package
Main:ClearWeather(PackageType: string, PackageName: string)
This clears the weather package
Reminder: regions are handled automatically, hence why there is not any API for them
Here is some example code:
Server
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local IEFolder = ReplicatedStorage.IE
local IEMain = require(IEFolder.Main)
IEMain:Run()
IEMain:SetServerPackage("Audio", "Default")
IEMain:SetServerPackage("Lighting", "Default")
Client
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local IEFolder = ReplicatedStorage:WaitForChild("IE")
local Main = require(IEFolder:WaitForChild("Main"))
Main:Run()
Assuming I have two packages, one audio package called “Default” and another lighting package called “Default”, this will work perfectly.
I highly recommend playing around in the example place to get an idea of how to deploy IE V2.
Settings are included and described within the module. They are very similar to the V1 settings with some changes, removals, and additions.
How is IE V2 Functionally Different, i.e. the Nitty Gritty?
Details
Firstly, IE V2 is different enough to the point where there is zero backwards compatibility with previous versions of IE or configurations. It’s really easy to switch over though, and specific instructions are provided in the following section.
How IE V1 worked
IE V1 worked by essentially running a package system on the server. When a player entered a region or when weather was generated, the server settings would be interrupted and the settings for the region or weather would be applied. As mentioned in the example above, this works for a lot of cases.
How IE V2 worked
IE V2 is way cleaner internally and works in a much smarter way. IE now can simultaneously process three packages simultaneously and apply the settings based on the specified scope. What this means is that when you enter a region, for example, the server package remains loaded in the background so that you can quickly and accurately switch back over to it when you leave the region. This is not performance intensive, and actually boosts performance by reducing the amount of times the client or server must read new packages.
IE is built to allow better direct control by the developer during run-time. V1 was very much of a “create your settings and let it run”. V2 captures that same spirit, so that IE remains useful to non-programmers and programmers alike, but allows for much-needed control to ensure that IE behaves exactly how you want it too.
IE is also compatible with CullingService. One of the big limitations to IE, was that I wasn’t able to use it in tandem with CullingService, because parts that were loaded in would not be adjusted by the lighting system. IE V2 fixes this, and allows for CullingService compatibility to be toggled on and off. This way, you can continue to maximize performance.
How to Switch from IE V1 iterations to IE V2
Conversion Steps
V2 is not backwards compatible with previous versions of IE. There are significant changes to the API which require you to ‘launch’ IE yourself. Below are instructions.
- Convert your previous lighting settings to Package format. To see how this is done, check out the example place. It’s pretty straight forward!
- Require Main
- Call
Main:Run()
- Set your server package for both audio and lighting, using
Main:SetServerPackage(“Audio”, PackageNameHere) and Main:SetServerPackage(“Lighting”, PackageNameHere)
A default lighting and audio package must be assigned to the server. If you don’t want server or audio packages, just create one with the same start and end times that has no changes. Internally, though, it’s important that there is one set
Legacy Downloads
IE V1 Legacy Model.rbxm (53.2 KB)
IE V1 Legacy Example Place.rbxl (82.9 KB)
Because IE V2 is not backwards compatible, the latest V1 variant has been included for your convenience. This should function perfectly fine, however, I highly recommend using IE V2 for more control.
Enjoy!
