Getting Started

Welcome to Riptide! This guide will walk you through installing the framework, writing your first service, and launching your game.

1. Installation

Via Pesde (Recommended)

Install Pesde. In your game folder, run pesde init and choose roblox and pesde/scripts_rojo. Then run:

pesde add riptide/core@0.8.2 --alias Riptide
pesde install

Result: pesde.toml lists Riptide, and the package is under roblox_packages/.

Wally availability

The v0.8.2 source tag contains a wally.toml for riptide/core, but v0.8.2 is not listed in the Wally index. Use the pinned Pesde dependency above or the .rbxm release instead.

Manual Installation (.rbxm)

If you prefer not to use a package manager, download Riptide.rbxm from the v0.8.2 release and explicitly place it as ReplicatedStorage/Packages/Riptide in Studio. For manual installation, remove the Packages mapping from the Rojo project below.

---

2. Rojo Setup

If you are using Rojo to sync your code into Roblox Studio, here is the recommended default.project.json configuration. It properly routes your packages, server scripts, client scripts, and shared modules:

{
  "name": "riptide-project",
  "tree": {
    "$className": "DataModel",
    "ReplicatedStorage": {
      "Packages": {
        "$path": "roblox_packages"
      },
      "SharedModules": {
        "$path": "src/shared"
      }
    },
    "ServerScriptService": {
      "main": {
        "$path": "src/server/main.server.lua"
      },
      "Services": {
        "$path": "src/server/Services"
      }
    },
    "StarterPlayer": {
      "StarterPlayerScripts": {
        "main": {
          "$path": "src/client/main.client.lua"
        },
        "Controllers": {
          "$path": "src/client/Controllers"
        }
      }
    }
  }
}

This produces the following hierarchy inside Roblox Studio:

ServerScriptService/
├── main                    (Script)
└── Services/               (Folder)

StarterPlayer/StarterPlayerScripts/
├── main                    (LocalScript)
└── Controllers/            (Folder)

ReplicatedStorage/
├── Packages/               (installed dependencies)
└── SharedModules/          (shared code)

---

3. Your First Service

In Riptide, game logic lives inside modules (Services on the server, Controllers on the client).

Let’s create a simple Server service that prints a message when a player joins.

1. Create a Folder in ServerScriptService and name it Services.
2. Inside Services, create a ModuleScript named HelloService.
3. Paste the following code:

-- ServerScriptService/Services/HelloService.lua
local HelloService = {}

-- The `:` colon syntax means `self` (HelloService table) is the implicit first argument.
-- `Riptide` is the framework reference passed as the second argument.
function HelloService:Init(Riptide)
    print("HelloService initialized!")
end

function HelloService:Start(Riptide)
    print("HelloService started!")
end

function HelloService:OnPlayerAdded(Riptide, player)
    print("Welcome to the game, " .. player.Name .. "!")
end

return HelloService

Riptide will automatically call Init (synchronously), then Start (via task.spawn). The OnPlayerAdded hook fires whenever a player joins the server.

Note

Inside OnPlayerAdded, always use the Riptide argument (not self.State or other fields set during Init) to access framework APIs. See Player Lifecycle for details.

---

4. Launching the Framework

Riptide does not start automatically. You must explicitly tell it where your modules are and launch it from both the server and client.

Server Entry Point

Create a standard Script inside ServerScriptService (e.g., main.server.lua):

-- ServerScriptService/main.server.lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ServerScriptService = game:GetService("ServerScriptService")

local Riptide = require(ReplicatedStorage.Packages.Riptide)

Riptide.Server.Launch({
    ModulesFolder = ServerScriptService.Services,
    SharedModulesFolder = ReplicatedStorage.SharedModules, -- optional
})

Client Entry Point

Create a LocalScript inside StarterPlayerScripts (e.g., main.client.lua):

-- StarterPlayer/StarterPlayerScripts/main.client.lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local Riptide = require(ReplicatedStorage.Packages.Riptide)

Riptide.Client.Launch({
    ModulesFolder = Players.LocalPlayer.PlayerScripts.Controllers,
    SharedModulesFolder = ReplicatedStorage.SharedModules, -- optional
})

Tip

SharedModulesFolder is optional. If provided, shared modules are loaded before side-specific modules, so services and controllers can depend on shared code during Init. See Project Structure for details.

---

5. Play the Game!

Press Play in Roblox Studio. In your Output window, you should see:

🌊 [Riptide] Server Initialization Started...
HelloService initialized!
HelloService started!
🌊 [Riptide] ✅ Server Start Phase Dispatched.
Welcome to the game, Player1!

Congratulations! You’ve successfully built your first Riptide project.

Next Steps

To learn more about how Riptide structures a full game, check out:

• Project Structure — How to organize your folders.
• Module Lifecycle — How the Load/Init/Start cycle works in detail.