Data model

Every place is represented by a data model, a hierarchy of objects that describe everything about the place. The data model contains all objects that make up the 3D world, such as parts, terrain, lighting, and other environmental elements. It also contains objects that can control runtime behavior, such as scripts that modify properties, call methods and functions, and respond to events that enable dynamic behavior and interactivity.

The Roblox Engine uses the data model as a source of truth for a place's state, so it can simulate and render it on client devices. For more information on how the Roblox Engine interprets the data model, see Client-Server Runtime.

Objects#

You place and organize objects in the data model to describe a place in Roblox. Every object in Roblox inherits from the Instance class, which defines generic properties, methods, and events that are common to all objects. Objects also define their own characteristics depending on the functionality the object provides. There are many categories of objects with a wide variety of uses, but you'll frequently work with BasePart and LuaSourceContainer objects, commonly referred to as parts and scripts.

For a comprehensive list of all the features of the Roblox Engine, see the reference documentation.

3D building blocks#

BasePart is the core class for physically-simulated 3D building blocks in the world. It defines the properties and methods common to all physical objects with properties like position, size, and orientation.

While you can theoretically create a fully functional Roblox game using just simple parts, you'll most likely import meshes and combine primitive parts into more complex objects and structures through solid modeling.

Scripts#

You can add interactivity and behavior to your place's 3D world and define logic with scripts. You write scripts in the Luau programming language to do things like moving parts, calling other scripts, and responding to events. Because Roblox works in a client-server model, you can run scripts on the server, client, or have them communicate across the network boundary.

• A Script object represents a script that can only run on the server.
• A LocalScript object represents a script that can only run on the client.
• A ModuleScript object represents a reusable script that you can LuaGlobals.require() from both server and client scripts.

For scripts to behave properly, you must place them in the correct containers in the data model. For more information, see the Server and Client sections.

Object organization#

While you have a lot of flexibility in how you organize your data model, the Roblox Engine expects certain objects to be in certain container services which are objects that have specific behaviors and can affect the behaviors of the objects they contain. The main categories of container services include:

• Workspace — Workspace stores all objects that render in the 3D world.
• Environment — Containers like Lighting and SoundService that contain objects for environmental settings and elements.
• Replication — Containers for content and logic that replicates between the server and client, such as ReplicatedStorage and ReplicatedFirst.
• Server — Containers for server-side only content and logic, such as ServerScriptService and ServerStorage.
• Client — Containers for client-side content and logic, such as StarterPlayer and StarterGui.
• Chat — Containers for objects that enable chat features, such as VoiceChatService and TextChatService.

In addition, you can further organize your objects with the following objects:

• Folders — A Folder is for organizational purposes and doesn't define any behavior. For example, you can use folders to group similar objects like a set of scripts in server storage.
• Models — A Model is mainly intended for geometric groupings of parts, such as grouping together a desk set that includes a chair, table, and a lamp. To organize more complex sets, you can even nest models within models.

Workspace#

Workspace contains all objects that make up a place's 3D world. You can add objects to the workspace to customize your 3D world, such as base parts, mesh parts, and models. Clients render everything that appears in this container and nothing outside of it, so you can control what users see and interact with in your place. Although not actually rendered, you can also add scripts that are parented to the parts and models that they are associated with. By default, the workspace is pre-populated with a Terrain and Camera object.

Camera

Camera determines how the client views the 3D world. By default, there is one camera in the workspace, but you can add multiple camera objects for creating different perspectives and views. Every client takes these settings and creates its own camera view that the server can't directly modify.

For example, you can set a camera to follow user movements or stay fixed in a particular location. You can also adjust the field of view, distance, and angle to create different visual effects of how users view your 3D world.

For more information, see customize the camera.

Terrain

Terrain lets you create landscapes for your place. You can apply a material to the terrain to simulate desired natural environments, such as grass, water, sand, or a custom material. Though you can only have one terrain object for your 3D world and apply one material to that terrain, you can use the Terrain Editor to edit regions of your terrain.

For more information, see environmental terrain.

Environment#

Custom lighting can make your 3D world much more immersive and realistic. The Lighting service contains objects that control global lighting settings of your place, such as Atmosphere for simulating atmospheric effects or Sky to alter the sun, moon, and stars in your environments. In addition, you can use light sources to emit light from specific objects.

Adding audio to your games is also crucial for elevating your games to new heights. By strategically using positional and non-positional audio, you can immerse players into your worlds, provide them useful feedback for their actions, and direct their attention to what they need to do to be successful in their objectives.

Replication#

Replication is the process of the server synchronizing the state of your place with all connected clients. The Roblox Engine intelligently and automatically replicates data, physics, and chat messages between the server and client for many cases, but you can also specify certain objects to replicate by placing them in specific containers.

ReplicatedFirst

ReplicatedFirst contains objects that you want to replicate to a client when it joins your place. It typically contains objects that are essential to initialize a player, such as client-side LocalScript objects and the objects associated with the scripts. All content in this container is replicated from the server to the client only once.

ReplicatedStorage

ReplicatedStorage contains objects that are available to both the server and connected clients. Any changes that occur on the client persist but won't be replicated to the server. The server can overwrite changes on the client to maintain consistency. This container is typically used for ModuleScript objects that need to be shared and accessed by both Script (server-side) and LocalScript (client-side) objects. In addition, you can use this container to replicate any objects that don't need to exist in the 3D world until needed, such as a ParticleEmitter for cloning and parenting to all incoming character models.

For more information on how replication works, see client-server runtime.

Server#

The data model defines dedicated containers for server-side only objects that are never replicated to the client. This allows the server to affect client behavior and state without exposing the server's objects and logic to the client.

ServerScriptService

ServerScriptService contains Script objects, ModuleScript objects that are required by server scripts, and other scripting-related objects that are only meant for server use. If your scripts require other, non-scripting objects, you must place them in ServerStorage. Scripts in this container are never replicated to clients, which allows you to have secure, server-side logic.

ServerStorage

ServerStorage contains objects that are only meant for server use. You can use this container to store objects that you want to clone and parent to the workspace or other containers at runtime. For example, you can store large objects such as maps in this container until they are needed and move them into the workspace only when required. This lets you decrease client network traffic on initial join.

Client#

The client container services are meant for objects that are replicated to every connected client. This category of containers replicate to every connected client and typically contain 3D objects and associated LocalScript objects. All objects you store in these containers are non-persistent across sessions and reset every time a client rejoins. You can put objects in these containers such as player GUIs, client-side scripts, and other objects that are only relevant to the client.

When a client connects to a server, the Players container service listens for users joining your place and creates a Player object for every client. The server copies the objects from the client containers in the edit data model to the corresponding location in the runtime data model inside the Players object. The following table describes the original container it resides on in the container and the resulting container they are copied to on the client:

Chat#

TextChatService

TextChatService represents the service that handles various, in-game text chat tasks, such as managing channels, decorating messages, filtering text, creating commands, and developing custom chats interfaces.

For more information, see text chat overview.

VoiceChatService

VoiceChatService represents the proximity-based voice chat feature that simulates realistic communication based on how close you are to other users. You can use this service to toggle the feature on and off.

For more information, see voice chat.

Folders and models#

There are two primary methods for grouping objects in the data model: folders and models. Both are containers for objects, but they have different purposes.

• Folders are best for storing sections of an environment, such as the lobby or a combat arena.
• Models are used for sets of objects, such as a desk set that includes a chair, table, and a lamp. To organize more complex sets, nest models inside models.

You should always name your objects descriptively. This makes it easy to find and modify objects later on if needed.