Every place is represented by a data model, a hierarchy of objects that describeeverything about the place. The data model contains all objects that make up the3D world, such as parts, terrain, lighting, and other environmental elements. Italso contains objects that can control runtime behavior, such as scripts thatmodify properties, call methods and functions, and respond to events that enabledynamic 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 howthe Roblox engine interprets the data model, see Client-ServerRuntime.
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 definesgeneric properties, methods, and events that are common to all objects. Objectsalso define their own characteristics depending on the functionality the objectprovides. There are many categories of objects with a wide variety of uses, butyou'll frequently work with BasePart and LuaSourceContainerobjects, commonly referred to as parts and scripts.
For a comprehensive list of all the features of the Roblox engine, see thereference 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.
| Object | Description |
|---|---|
| Part | A primitive part that can take the shape of a block, ball, cylinder, wedge, or corner wedge. |
| MeshPart | An imported mesh from 3D modeling software like Maya or Blender. |
| TrussPart | A truss beam that characters can climb like a ladder. |
While you can theoretically create a fully functional Roblox experience usingjust simple parts, you'll most likely import meshes and combine primitive parts into more complex objects and structures through solidmodeling.
Scripts
You can add interactivity and behavior to your place's 3D world and define logicwith scripts. You write scripts in the Lua programming language to do thingslike moving parts, calling other scripts, and responding to events. BecauseRoblox 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 theclient.
A ModuleScript object represents a reusable script that you canrequire() from bothserver and client scripts.
For scripts to behave properly, you must place them in the correct containers inthe 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, theRoblox engine expects certain objects to be in certain container serviceswhich are objects that have specific behaviors and can affect the behaviors ofthe objects they contain. The main categories of container services include:
Workspace - Workspace stores all objects that render in the 3Dworld.
Environment - Containers like Lighting and SoundServicethat contain objects for environmental settings and elements.
Replication - Containers for content and logic that replicates between theserver and client, such as ReplicatedStorage andReplicatedFirst.
Server - Containers for server-side only content and logic, such asServerScriptService and ServerStorage.
Client - Containers for client-side content and logic, such asStarterPlayer and StarterGui.
Chat - Containers for objects that enable chat features, such asVoiceChatService and TextChatService.
The Roblox engine has many more services that providebuilt-in functionality that you can call within your scripts. The Roblox enginedoesn't give these services special treatment in the data model. For moreinformation, see Services.
In addition, you can further organize your objects with the following objects:
Folders - A Folder is for organizational purposes and doesn'tdefine any behavior. For example, you can use folders to group similar objectslike a set of scripts in server storage.
Models - A Model is mainly intended for geometric groupings ofparts, such as grouping together a desk set that includes a chair, table, anda 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 canadd objects to the workspace to customize your 3D world, such as base parts,mesh parts, and models. Clients render everything that appears in this containerand nothing outside of it, so you can control what users see and interact within your place. Although not actually rendered, you can also add scripts that areparented to the parts and models that they are associated with. By default, theworkspace is pre-populated with a Terrain and Camera object.
Camera
Camera determines how the client views the 3D world. By default, thereis one camera in the workspace, but you can add multiple camera objects forcreating different perspectives and views. Every client takes these settings andcreates 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 aparticular location. You can also adjust the field of view, distance, and angleto create different visual effects of how users view your 3D world.
For more information, see Customizing the Camera.
Terrain
Terrain lets you create landscapes for your place. You can apply amaterial to the terrain to simulate desired natural environments, such as grass,water, sand, or a custom material. Though you can only have one terrain objectfor your 3D world and apply one material to that terrain, you can use theTerrain Editor to edit regions of yourterrain.
For more information, see Environmental Terrain.
Environment
Lighting and sound effects can make your 3D world much more immersive andrealistic. Although it isn't necessary to add these effects to your place, theycan make it more visually and aurally appealing.
In addition to using the light and sound services, youcan add parts that emit light and sound. For more information, seeLighting Effects andSound Objects.
Lighting
Lighting contains objects that control global lighting settings of yourplace, such as Atmosphere for simulating atmospheric effects orSky to alter the sun, moon, and stars in your environments.
For more information, see Lighting.
Sound
SoundService can control volume and playback settings of childSound objects for background music or environmental sound effects.
For more information, see Sound.
Replication
Replication is the process of the server synchronizing the state of yourplace with all connected clients. The Roblox engine intelligently andautomatically replicates data, physics, and chat messages between the server andclient for many cases, but you can also specify certain objects to replicate byplacing them in specific containers.
ReplicatedFirst
ReplicatedFirst contains objects that you want to replicate to a clientwhen it joins your place. It typically contains objects that are essential toinitialize a player, such as client-side LocalScript objects and theobjects associated with the scripts. All content in this container is replicatedfrom the server to the client only once.
ReplicatedStorage
ReplicatedStorage contains objects that are available to both the serverand connected clients. Any changes that occur on the client persist but won't bereplicated to the server. The server can overwrite changes on the client tomaintain consistency. This container is typically used for ModuleScriptobjects that need to be shared and accessed by both Script (server-side)and LocalScript (client-side) objects. In addition, you can use thiscontainer to replicate any objects that don't need to exist in the 3D worlduntil needed, such as a ParticleEmitter for cloning and parenting to allincoming 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 thatare never replicated to the client. This allows the server to affect clientbehavior and state without exposing the server's objects and logic to theclient.
You can use remote events and functions to allowclient-side communication with the server.
ServerScriptService
ServerScriptService contains Script objects,ModuleScript objects that are required by server scripts, and otherscripting-related objects that are only meant for server use. If your scriptsrequire other, non-scripting objects, you must place them inServerStorage. Scripts in this container are never replicated toclients, which allows you to have secure, server-side logic.
ServerStorage
ServerStorage contains objects that are only meant for server use. Youcan use this container to store objects that you want to clone and parent to theworkspace or other containers at runtime. For example, you can store largeobjects such as maps in this container until they are needed and move them intothe workspace only when required This lets you decrease client network trafficon initial join.
Scripts don't run when they are parented to thiscontainer, but scripts inside ServerScriptService can access and runModuleScript objects in this container.
Client
The client container services are meant for objects that are replicated to everyconnected client. This category of containers replicate to every connectedclient and typically contain 3D objects and associated LocalScriptobjects. All objects you store in these containers are non-persistent acrosssessions and reset every time a client rejoins. You can put objects in thesecontainers such as player GUIs, client-side scripts, and other objects that areonly relevant to the client.
When a client connects to a server, the Players container servicelistens for users joining your place and creates a Player object forevery client. The server copies the objects from the client containers in theedit data model to the corresponding location in the runtime data model insidethe Players object. The following table describes the original containerit resides on in the container and the resulting container they are copied to onthe client:
| Edit Data Model | Runtime Data Model | Notes |
|---|---|---|
| StarterPack | Player.Backpack | Scripts that set up the player's inventory and generally contain Tool objects but often contains local scripts as well. |
| StarterGui | Player.PlayerGui | Scripts that can manage the player's local GUI. When a player respawns, the contents of PlayerGui are emptied. The server copies the objects inside StarterGui into the PlayerGui. |
| StarterPlayerScripts | Player.PlayerScripts | General purpose scripts for the client. For example, if you want to create special effects on the client when certain conditions are met, you can place a local script in this container to do that. The server cannot access this container. |
| StarterCharacterScripts | Player.Character | Scripts that are copied to the client when they spawn. These scripts do not persist when the player respawns. |
| ReplicatedFirst | The contents of this container are replicated to all clients (but not back to the server) first, before anything else. |
For more information on edit and runtime data models,see Client-Server Runtime.
You don't add Player objects to the Players containerservice explicitly.
Chat
TextChatService
TextChatService represents the service that handles various,in-experience text chat tasks, such as managing channels, decorating messages,filtering text, creating commands, and developing custom chats interfaces.
For more information, see In-Experience Text Chat System.
VoiceChatService
VoiceChatService represents the proximity-based voice chatfeature that simulates realistic communication based on how close you are toother users. You can use this service to toggle the feature on and off.
For more information, see Chat with Voice.
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 havedifferent 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 tofind and modify objects later on if needed.
