### Implement complete production-ready server script

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ServerSetup.md

A comprehensive example combining scene initialization, player tracking, and network replication handling into a single robust server-side script.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local UpsideEngine = require(ReplicatedStorage.Packages.UpsideEngine)
local networkingService = UpsideEngine.GetService("NetworkingService")
local authorityService = UpsideEngine.GetService("AuthorityService")
local sceneManager = UpsideEngine.GetService("SceneManager")

-- State tracking
local characters = {}
local scene = nil

-- Initialize server
local function initialize()
    -- Find the game scene
    scene = sceneManager:FindByName("game")
    while not scene do
        scene = sceneManager:FindByName("game")
        task.wait()
    end
    
    print("Server initialized successfully")
end

-- Handle replication requests
networkingService:On("ReplicationRequest", function(request)
    local content = request.Content
    local player = Players:GetPlayerByUserId(request.ClientId)
    
    if not player then
        print("Warning: Received request from unknown player")
        return
    end
    
    -- Accept the object
    local object = request:Accept()
    
    -- Handle different object types
    if content.ClassName == "Character" then
        -- Track the player's character
        if not characters[player] then
            authorityService:SetAuthority(object, "Client")
            characters[player] = object
            print(player.Name .. " joined the game")
        end
    else
        -- For other objects, grant authority
        authorityService:SetAuthority(object, "Client")
    end
end)

-- Handle player disconnections
Players.PlayerRemoving:Connect(function(player)
    characters[player] = nil
    print(player.Name .. " left the game")
end)

-- Start the server
initialize()
```

--------------------------------

### Example: Shop Interaction Prompt

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/proximity-prompt/Introduction.md

A complete example demonstrating the setup of a ProximityPrompt2D for interacting with a shop. It configures the prompt's range, assigns a custom action name, and binds it to a specific key press.

```lua
local ProximityPrompt = UpsideEngine.new("ProximityPrompt2D")
ProximityPrompt.Instance.Position = UDim2.new(0, 0, 0, -250)
ProximityPrompt:SetScene(Scene)
ProximityPrompt.Range = 500
ProximityPrompt.ActionName = "OpenShop"

CrossPlatformService:SetDeviceKey("Keyboard", "F", "OpenShop")
```

--------------------------------

### Basic Server Setup Script (Lua)

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ServerSetup.md

This script provides a minimal server setup for UpsideEngine. It listens for replication requests from clients, accepts them, and critically, grants authority to the client to allow for subsequent updates.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local UpsideEngine = require(ReplicatedStorage.Packages.UpsideEngine)
local networkingService = UpsideEngine.GetService("NetworkingService")
local authorityService = UpsideEngine.GetService("AuthorityService")

-- Handle replication requests from clients
networkingService:On("ReplicationRequest", function(request)
    -- Accept the request and create the object
    local object = request:Accept() 
    
    -- CRITICAL: Grant authority to the client
    -- Without this, the client won't be able to update the object!
    authorityService:SetAuthority(object, "Client")
end)
```

--------------------------------

### Initialize game scene on the server

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ServerSetup.md

Shows how to retrieve a specific scene using the SceneManager and wait until it is fully loaded before performing server-side operations.

```lua
local sceneManager = UpsideEngine.GetService("SceneManager")
local scene = sceneManager:FindByName("game") -- Find your scene

-- Wait for the scene to be ready
while not scene do
    scene = sceneManager:FindByName("game")
    task.wait()
end

-- Now you can do server-side operations
print("Server scene is ready!")
```

--------------------------------

### Full Implementation Example

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/reactive-label/TextTags.md

A complete example showing the initialization of a ReactiveLabel, the application of multiple nested tags including wave and gradient, and the final rendering call.

```lua
local reactiveLabel = upsideEngine.new("ReactiveLabel")
reactiveLabel.Instance.Parent = dialogBox
reactiveLabel.Instance.Size = UDim2.fromScale(1, 1)
reactiveLabel.Font = Enum.Font.Arcade
reactiveLabel.StopSoundOnFinish = false

reactiveLabel.Text = [[
    <wave intensity=6 duration=1><font color="#ff4500"> Hello!! </font></wave>
    I'm feeling good today,
    <wave><gradient startColor="#ff4500" endColor="#ff9933"> how are you? </gradient></wave>
]]

reactiveLabel:Render()
```

--------------------------------

### Initialize UpsideEngine Scene

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/shader-guide/FirstSteps.md

Sets up the core environment by initializing a ScreenGui and creating a new UpsideEngine scene instance to serve as the workspace.

```luau
local replicatedStorage = game:GetService("ReplicatedStorage")
local players = game:GetService("Players")

local packages = replicatedStorage.packages
local playerGui = players.LocalPlayer:WaitForChild("PlayerGui")

local upsideEngine = require(packages.UpsideEngine)
local screen = Instance.new("ScreenGui")
screen.Name = "Screen"
screen.IgnoreGuiInset = true
screen.Parent = playerGui

local scene = upsideEngine.new("Scene")
scene.Instance.Parent = screen
scene:SetName("MyScene") 
scene:Enable()
```

--------------------------------

### Server Authority vs. Client Authority Comparison (Lua)

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ServerSetup.md

This example contrasts two scenarios for handling replication requests: one where the server retains authority (leading to frozen characters for other players) and another where authority is explicitly granted to the client (enabling smooth synchronization).

```lua
-- Without authority assignment
networkingService:On("ReplicationRequest", function(request)
    request:Accept()
    -- Server now has authority
end)
```

```lua
-- With authority assignment
networkingService:On("ReplicationRequest", function(request)
    local object = request:Accept()
    authorityService:SetAuthority(object, "Client")
    -- Client now has authority
end)
```

--------------------------------

### Install Upside Engine with Wally

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/get-started/Installation.md

Integrates the Upside Engine into your project using the Wally package manager. This involves adding a dependency line to your `wally.toml` configuration file.

```toml
UpsideEngine = "notreux/upsideengine@3.0.0"
```

--------------------------------

### Create Player Character with UpsideEngine

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ClientSetup.md

Defines and configures a player character for the game, including its visual properties, physics, sprite sheets for animations, and control setup. It also integrates the character with the game's scene and camera.

```lua
local character = UpsideEngine.new("Character")
character:SetScene(scene)

-- Basic properties
local size = 256
character.Instance.Position = UDim2.fromOffset(400, 300)
character.Instance.Size = UDim2.fromOffset(size, size)
character.Instance.ImageRectSize = Vector2.new(64, 64)
character.Instance.ZIndex = 100

-- Physics properties
character.Mass = 0
character.WalkSpeed = 200
character.SecondsPerFrame = 1 / 10

-- Set up sprite sheets for different animations
character:SetSpriteSheet("idle_down", "rbxassetid://yourIdleDownId", Vector2.new(4, 1))
character:SetSpriteSheet("walk_down", "rbxassetid://yourWalkDownId", Vector2.new(4, 1))
character:SetSpriteSheet("idle_up", "rbxassetid://yourIdleUpId", Vector2.new(4, 1))
character:SetSpriteSheet("walk_up", "rbxassetid://yourWalkUpId", Vector2.new(4, 1))
-- Add more sprite sheets as needed...

-- Start with an idle animation
character:Play("idle_down")

-- Configure player controls and camera
crossPlatformService.SideView = false
crossPlatformService:SetPlayerCharacter(character)
scene.Camera:SetSubject(character)
```

--------------------------------

### Load and Unload Server Modules (Luau)

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/style-guide/ModuleManagement.md

This Luau script demonstrates how to load and unload server-side modules using a `setup` utility. It fetches modules from ReplicatedStorage, loads and starts them, and ensures they are properly unloaded when the game closes.

```lua
local replicatedStorage = game:WaitForChild("ReplicatedStorage")
local setup = require(replicatedStorage.shared.util.setup)
local modules = setup.getModulesByPath(script.Parent:WaitForChild("modules"))

-- Unload all modules when required.
local function unloadModules()
    setup.run(modules, "unload")
end

-- Load and start all server-side modules.
local function loadModules()
    setup.run(modules, "load")
    setup.run(modules, "start")
end

-- Load modules
loadModules()

-- Ensure that modules are unloaded properly when the game is closing.
game:BindToClose(function()
    unloadModules()
end)
```

--------------------------------

### Install Upside Engine with Git Submodules

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/get-started/Installation.md

Adds the Upside Engine as a Git submodule to your project's packages directory. This method is useful for managing external dependencies directly within your version control system.

```git
git submodule add https://github.com/notreux/UpsideEngine packages/UpsideEngine
```

--------------------------------

### Create Game Environment with UpsideEngine

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ClientSetup.md

Creates a static object to serve as the terrain or background for the game environment. It configures its position, size, image, and ZIndex within the specified scene.

```lua
-- Create a terrain/background
local terrain = UpsideEngine.new("StaticObject")
terrain:SetScene(scene)

local terrainInstance = terrain.Instance
terrainInstance.Position = UDim2.fromOffset(0, 0)
terrainInstance.Size = UDim2.fromOffset(800, 800)
terrainInstance.Image = "rbxassetid://yourTerrainId"
terrainInstance.ZIndex = 1
```

--------------------------------

### Initialize UpsideEngine Client and Character

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ClientSetup.md

This script demonstrates how to initialize the UpsideEngine services, create a game scene, spawn a player character with sprite animations, and enable network replication. It relies on the UpsideEngine library to manage scene objects and cross-platform synchronization.

```lua
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local packages = ReplicatedStorage.Packages
local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui")

local UpsideEngine = require(packages.UpsideEngine)
local networkingService = UpsideEngine.GetService("NetworkingService")
local crossPlatformService = UpsideEngine.GetService("CrossPlatformService")

-- Setup screen and scene
local screen = Instance.new("ScreenGui")
screen.Name = "MultiplayerGame"
screen.IgnoreGuiInset = true
screen.Parent = playerGui

local scene = UpsideEngine.new("Scene")
scene.Instance.Parent = screen
scene:Enable()

-- Create environment
local terrain = UpsideEngine.new("StaticObject")
terrain:SetScene(scene)
terrain.Instance.Position = UDim2.fromOffset(0, 0)
terrain.Instance.Size = UDim2.fromOffset(800, 800)
terrain.Instance.Image = "rbxassetid://yourTerrainId"

-- Create player character
local character = UpsideEngine.new("Character")
character:SetScene(scene)
character.Instance.Position = UDim2.fromOffset(400, 300)
character.Instance.Size = UDim2.fromOffset(256, 256)
character.Instance.ImageRectSize = Vector2.new(64, 64)
character.Mass = 0
character.WalkSpeed = 200

character:SetSpriteSheet("idle", "rbxassetid://yourIdleId", Vector2.new(4, 1))
character:Play("idle")

crossPlatformService.SideView = false
crossPlatformService:SetPlayerCharacter(character)
scene.Camera:SetSubject(character)

-- Start replication
networkingService:ReplicateOnChange(character)

-- Handle other players' characters
networkingService:On("Build", function(object)
    object:SetScene(scene)
end)
```

--------------------------------

### Basic Client Structure with UpsideEngine

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ClientSetup.md

Sets up the fundamental structure for a client in an Upside Engine multiplayer game. It initializes necessary services, creates a screen GUI for the game, and instantiates and enables the main game scene.

```lua
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local packages = ReplicatedStorage.Packages
local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui")

-- Load Upside Engine
local UpsideEngine = require(packages.UpsideEngine)

-- Get required services
local networkingService = UpsideEngine.GetService("NetworkingService")
local crossPlatformService = UpsideEngine.GetService("CrossPlatformService")

-- Create the screen container
local screen = Instance.new("ScreenGui")
screen.Name = "MultiplayerGame"
screen.IgnoreGuiInset = true
screen.Parent = playerGui

-- Create and configure the scene
local scene = UpsideEngine.new("Scene")
scene.Instance.Parent = screen
scene:SetName("GameScene")
scene:Enable()
```

--------------------------------

### Initialize Upside Engine Server Script

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/get-started/Installation.md

A Lua script to initialize the Upside Engine on the server. This is a mandatory step for the engine to function correctly, even if you are not using server-side features, as some services depend on server initialization.

```lua
local replicatedStorage = game:GetService("ReplicatedStorage")
local packages = replicatedStorage.packages

local upsideEngine = require(packages.UpsideEngine)
print("Upside Engine version: " .. upsideEngine.Version)
```

--------------------------------

### Initialize Scene and Lighting Environment in UpsideEngine

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/lighting-guide/Introduction.md

This script initializes the UpsideEngine scene, configures the lighting environment parameters, and sets up the rendering style. It requires the UpsideEngine module and assumes a 'Game' GUI element exists in the PlayerGui.

```lua
local RunService = game:GetService("RunService")  
local PlayerGui = game.Players.LocalPlayer:WaitForChild("PlayerGui")  
local UpsideEngine = require(game.ReplicatedStorage:WaitForChild("UpsideEngine"))  

local SceneManager = UpsideEngine.GetService("SceneManager")  
local NetworkingService = UpsideEngine.GetService("NetworkingService")  
local CrossPlatformService = UpsideEngine.GetService("CrossPlatformService")  
CrossPlatformService.SideView = true  

local mouse = game.Players.LocalPlayer:GetMouse()  
local scene = UpsideEngine.new("Scene")  
scene.Instance.Parent = PlayerGui:WaitForChild("Game")  
scene:Enable()

-- Only visible lights will be tracked
scene.OnlyTrackVisible = true  

-- Set the ambient color of the lighting environment to black
scene.LightingEnvironment.AmbientColor = Color3.fromRGB(0, 0, 0)  

-- Define the ambient transparency; lower values mean less transparency
scene.LightingEnvironment.AmbientTransparency = 0.02 

-- Set the resolution of each chunk (tile) in the lighting environment to 64x64 pixels
scene.LightingEnvironment.ChunkResolution = Vector2.new(64, 64)  

-- Specify that there will be 1 column of chunks in the lighting environment
scene.LightingEnvironment.ChunkColumns = 1  

-- Choose the light resampling mode; Pixelated provides a retro, blocky look.
-- You can alternatively use Enum.ResamplerMode.Default for smoother results.
scene.LightingEnvironment.LightStyle = Enum.ResamplerMode.Pixelated  
scene.LightingEnvironment:DrawPixels()
```

--------------------------------

### Create and Configure ProximityPrompt2D

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/proximity-prompt/Introduction.md

Demonstrates how to instantiate a ProximityPrompt2D, set its scene, position, range, and attach it to a game object. This is the basic setup for enabling proximity-based interactions.

```lua
local ProximityPrompt = UpsideEngine.new("ProximityPrompt2D")
ProximityPrompt:SetScene(Scene)
ProximityPrompt.Instance.Position = UDim2.new(0, 0, 0, -250)
ProximityPrompt.Range = 500
ProximityPrompt:Attach(car)
```

--------------------------------

### Define default controller configuration

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/autogen/CrossPlatformService.md

An example of the structure used for the 'Configs' property, defining the default key mappings for Keyboard, Gamepad, and Mobile devices.

```lua
{
	["Keyboard"]: {
		["W"]: "Up",
		["A"]: "Left",
		["S"]: "Down",
		["D"]: "Right",
		["Space"]: "Up",
		["E"]: "Collect"
	},
	["Gamepad"]: {
		["ButtonA"]: "Jump",
		["Thumbstick1"]: { ["Up"]: "Up", ["Left"]: "Left", ["Down"]: "Down", ["Right"]: "Right" }
	},
	["Mobile"]: {
		["JumpButton"]: "Jump",
		["Thumbstick1"]: { ["Up"]: "Up", ["Left"]: "Left", ["Down"]: "Down", ["Right"]: "Right" }
	}
}
```

--------------------------------

### Recommended Rojo Project Template

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/get-started/Installation.md

A JSON configuration for Rojo, a tool that synchronizes your local file system with your Roblox project. This template sets up the necessary folder structure for Upside Engine, including ReplicatedStorage, StarterPlayerScripts, and ServerScriptService.

```json
{
    "name": "My first 2D Game",
    "tree": {
        "$className": "DataModel",
        "ReplicatedStorage": {
            "$className": "ReplicatedStorage",
            "packages": {
                "$className": "Folder",
                "$path": "packages"
            }
        },
    
        "StarterPlayer": {
            "$className": "StarterPlayer",
            "StarterPlayerScripts": {
                "$className": "StarterPlayerScripts",
                "client":{
                    "$path": "src/client"
                }
            }
        },

        "ServerScriptService": {
            "$className": "ServerScriptService",
            "server": {
                "$path":"src/server"
            }
        }
    }
}
```

--------------------------------

### Configure Parallax Properties

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/autogen/Parallax.md

Example demonstrating how to initialize a Parallax object, set its texture, and configure tracking and camera locking behaviors.

```Luau
local parallax = Parallax.new()
parallax:SetTexture("rbxassetid://12345678")
parallax.CanvasSize = Vector2.new(2, 2)
parallax.Offset = Vector2.new(0, 0)
parallax.Track = true
parallax.LockToCamera = true
parallax:UpdateTiles()
```

--------------------------------

### Initialize and Configure Pointlight in UpsideEngine

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/lighting-guide/Pointlight.md

Demonstrates how to instantiate a new Light object, attach it to a scene, and define its shape, range, and color properties. This setup is essential for creating omnidirectional light sources in the game environment.

```lua
local pointlight = UpsideEngine.new("Light") -- Create a new Light object using UpsideEngine
pointlight:SetScene(scene)                   -- Attach the pointlight to the current scene
pointlight.Shape = "pointlight"              -- Set the light's shape to "pointlight", making it omnidirectional
pointlight.Range = 800                       -- Define the light's effective radius (how far the light reaches)
pointlight.Color = Color3.fromRGB(255, 0, 0) -- Set the light's color to red using RGB values
pointlight.Inverted = false                  -- Determine the rendering style: false for a standard pointlight
```

--------------------------------

### Initialize Upside Engine and Scene

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/plugin-guide/PluginScripts.md

This script initializes the Upside Engine services, loads plugin content, and sets up the player character and camera within a specified scene. It requires the engine to be placed in ReplicatedStorage.packages and should be run as a LocalScript in StarterPlayerScripts.

```lua
------------- SETTINGS -------------
local sceneName = "MyScene" -- Change "MyScene" for your scene name
local characterName = "MyCharacter" -- Change "MyCharacter" for your character name
local isPlatformer = true -- Change this to false if your game is not a platformer
------------------------------------
local replicatedStorage = game:GetService("ReplicatedStorage")
local playerGui = game:GetService("Players").LocalPlayer:WaitForChild("PlayerGui")

local packages = replicatedStorage:WaitForChild("packages")
local upsideEngine = require(packages:WaitForChild("UpsideEngine"))

local sceneManager = upsideEngine.GetService("SceneManager")
local crossPlatformService = upsideEngine.GetService("CrossPlatformService")
local pluginSupportService = upsideEngine.GetService("PluginSupportService")
pluginSupportService:LoadPluginContent()

local scene = sceneManager:FindByName(sceneName)
local character = scene.Objects:FindByName(characterName)

crossPlatformService.SideView = isPlatformer
crossPlatformService:SetPlayerCharacter(character)
scene.Camera:SetSubject(character)
scene:Enable()

local screenGui = Instance.new("ScreenGui")
screenGui.IgnoreGuiInset = true
screenGui.ResetOnSpawn = false
screenGui.Parent = playerGui
screenGui.ZIndexBehavior = Enum.ZIndexBehavior.Global
scene.Instance.Parent = screenGui
```

--------------------------------

### Create Static Objects

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/shader-guide/FirstSteps.md

Instantiates static objects within the scene, assigning textures and shaders to them. This demonstrates how to render visual elements like water or terrain.

```luau
local water = upsideEngine.new("StaticObject")
water:SetScene(scene)
water:SetShader(shader)

local instance = water.Instance
instance.Image = "rbxassetid://waterId"
instance.Size = UDim2.fromOffset(800, 800)

local terrain = upsideEngine.new("StaticObject")
terrain:SetScene(scene)

local instance = terrain.Instance
instance.Image = "rbxassetid://terrainId"
instance.Size = UDim2.fromOffset(800, 800)
```

--------------------------------

### Handle Other Players' Characters with UpsideEngine

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ClientSetup.md

Sets up an event listener for the 'Build' event provided by Upside Engine's networking service. This function is called when an object created by another player is received on the client, allowing it to be added to the current scene.

```lua
-- The Build event fires when an object from another player is created on your client
networkingService:On("Build", function(object)
    -- Add the object to your scene so it becomes visible
    object:SetScene(scene)
    
    -- You can also do additional setup here if needed
    -- For example, you might want to set a specific ZIndex or configure visuals
end)
```

--------------------------------

### Track player objects and character authority in Lua

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ServerSetup.md

Demonstrates how to monitor ReplicationRequests to identify character objects and assign client authority. It includes cleanup logic for player disconnections to prevent memory leaks.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local UpsideEngine = require(ReplicatedStorage.Packages.UpsideEngine)
local networkingService = UpsideEngine.GetService("NetworkingService")
local authorityService = UpsideEngine.GetService("AuthorityService")

-- Store each player's character
local characters = {}

networkingService:On("ReplicationRequest", function(request)
    local content = request.Content
    local player = Players:GetPlayerByUserId(request.ClientId)
    
    -- Check if this is a character
    if content.ClassName == "Character" then
        local character = request:Accept()
        
        -- Only grant authority if this is a new character for this player
        if not characters[player] then
            authorityService:SetAuthority(character, "Client")
            characters[player] = character
            
            print(player.Name .. "'s character replicated successfully")
        end
    else
        -- For other object types, accept and grant authority
        local object = request:Accept()
        authorityService:SetAuthority(object, "Client")
    end
end)

-- Clean up when players leave
Players.PlayerRemoving:Connect(function(player)
    characters[player] = nil
    print(player.Name .. " left the game")
end)
```

--------------------------------

### Enable Replication for Character with UpsideEngine

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ClientSetup.md

Configures the Upside Engine's networking service to replicate changes made to a character object. This ensures that the character's state is synchronized across the network to the server.

```lua
-- Start replicating the character
-- This will send replication data to the server
networkingService:ReplicateOnChange(character)
```

--------------------------------

### Initialize Upside Engine Scene

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/get-started/FirstGame.md

Sets up the initial environment by creating a ScreenGui and a new Scene object within the Roblox PlayerGui. This serves as the container for all 2D game elements.

```luau
local replicatedStorage = game:GetService("ReplicatedStorage")
local tweenService = game:GetService("TweenService")
local players = game:GetService("Players")

local packages = replicatedStorage.packages
local playerGui = players.LocalPlayer:WaitForChild("PlayerGui")

local upsideEngine = require(packages.UpsideEngine)
local screen = Instance.new("ScreenGui")
screen.Name = "MyGame"
screen.IgnoreGuiInset = true
screen.Parent = playerGui

local scene = upsideEngine.new("Scene")
scene.Instance.Parent = screen
scene:SetName("MyFirstScene")
scene:Enable()
```

--------------------------------

### Define and Apply Shader

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/shader-guide/FirstSteps.md

Creates a shader module script and applies it to a static object within the scene. The shader source is defined in a separate ModuleScript and linked via SetSource.

```luau
return function()
    -- shader code
end
```

```luau
local shader = upsideEngine.new("Shader")
shader:SetSource(script.Parent.Shader)
```

--------------------------------

### Initialize Module Utilities in Luau

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/style-guide/ModuleManagement.md

Provides helper functions to retrieve ModuleScripts from a specified path and execute lifecycle methods like load, start, or unload. This centralizes module management logic for both client and server environments.

```luau
local exports = {}

--[[
    Retrieves all ModuleScripts from a given path and requires them.
    Returns a table mapping module names to the required module. 
]] 
function exports.getModulesByPath(path)
    local modules = {}
    for _, module in path:GetChildren() do
        if module:IsA("ModuleScript") then
            modules[module.Name] = require(module)
        end
    end

    return modules
end

--[[
    Iterates over a table of modules and calls the specified method on each,
    passing any additional arguments provided.
]] 
function exports.run(modules, methodName, ...)
    for _, module in modules do
        if module[methodName] then
            module[methodName](...)
        end
    end
end

return exports
```

--------------------------------

### Sample Texture and Rotate Coordinates in Luau

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/shader-guide/IntegratedFunctions.md

Examples demonstrating how to sample pixel data from an ImageLabel using the texture function and perform coordinate rotation using the rotate function within a shading pipeline.

```lua
local replicatedStorage = game:GetService("ReplicatedStorage")
local packages = replicatedStorage:WaitForChild("packages")

local upsideEngine = require(packages:WaitForChild("UpsideEngine"))
local source = Instance.new("ImageLabel")
source.Image = "rbxassetid://cameraId"

@native
local function shadingFunction(params: upsideEngine.ShadingParams)
    local offset = Vector2.new(60, 80)
    local position = Vector2.new(params.x, params.y)
    local r, g, b, a = params.texture(source, position - offset)
    
    if a == 0 then
        return
    end    

    params.red = r
    params.green = g
    params.blue = b
    params.opacity = a
end

return shadingFunction
```

```lua
@native
local function shadingFunction(params: upsideEngine.ShadingParams)
    local clock = os.clock()    
    local speed = 25
    
    local centre = Vector2.new(64, 64)
    local position = Vector2.new(params.x, params.y)

	local rx, ry = params.rotate(centre, position, clock * speed)
    params.x = rx
	params.y = ry
end

return shadingFunction
```

--------------------------------

### Accessing Request Object Properties (Lua)

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/ServerSetup.md

This snippet demonstrates how to access important information within a `ReplicationRequest` object. It shows how to retrieve the client's ID, content details like class name, and the Roblox instance data before accepting the request.

```lua
networkingService:On("ReplicationRequest", function(request)
    -- Get information about the request
    local clientId = request.ClientId        -- The UserId of the player
    local content = request.Content          -- Information about the object
    local className = content.ClassName      -- Type of object ("Character", "StaticObject", etc.)
    local instance = content.Instance        -- The Roblox instance data
    
    -- Accept the request
    local object = request:Accept()
end)
```

--------------------------------

### Initialize and Render ReactiveLabel

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/reactive-label/Introduction.md

Demonstrates how to instantiate a ReactiveLabel, configure its appearance and behavior, and trigger the rendering process.

```lua
local reactiveLabel = upsideEngine.new("ReactiveLabel")
reactiveLabel.Instance.Parent = someGuiElement
reactiveLabel.Instance.Size = UDim2.fromScale(1, 1)
reactiveLabel.Font = Enum.Font.Arcade
reactiveLabel.StopSoundOnFinish = false

reactiveLabel.Text = [[
    <wave intensity=6 duration=1>
        <font color="#ff4500"> Hello!! </font>
    </wave>
    I'm feeling good today,
    <wave>
        <gradient startColor="#ff4500" endColor="#ff9933"> how are you? </gradient>
    </wave>
]]

reactiveLabel:Render()
```

--------------------------------

### Add Decorative Elements

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/get-started/FirstGame.md

Adds a non-collidable PhysicalObject to the scene for decoration, configured to cover the full screen resolution.

```luau
local decoration = upsideEngine.new("PhysicalObject")
decoration.TrackCollisions = false
decoration:SetScene(scene)

local decInstance = decoration.Instance
decInstance.Image = "rbxassetid://12993235175"
decInstance.Size = UDim2.fromOffset(1920, 1080)
decInstance.Position = UDim2.fromOffset(960, 540)
decInstance.ZIndex = 0
```

--------------------------------

### Configure device controls in Lua

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/autogen/CrossPlatformService.md

Methods to set individual device keys or bulk configure an entire device's control scheme using a dictionary.

```lua
-- Set a single key
CrossPlatformService:SetDeviceKey("Keyboard", "Space", "Up")

-- Set bulk configuration
CrossPlatformService:SetDeviceConfig("Keyboard", {
	W = "Up",
	A = "Left",
	S = "Down",
	D = "Right",
	Space = "Up"
})
```

--------------------------------

### Set and Get Object Authority (Lua)

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/autogen/AuthorityService.md

Demonstrates how to set and retrieve the authority for a game object using the AuthorityService. Authority can be assigned to 'Server' or 'Client'.

```lua
-- Set authority for an object to server
AuthorityService:SetAuthority(myObject, "Server")

-- Check authority
local authority = AuthorityService:GetAuthority(myObject)
if authority then
	print("Authority is assigned to:", authority)
end
```

--------------------------------

### Replicate client-side objects to server

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/HowItWorks.md

Demonstrates how a client initializes an object and signals the networking service to begin replication to the server.

```lua
local character = UpsideEngine.new("Character")
character:SetScene(scene)
-- Tell server to replicate this object
networkingService:ReplicateOnChange(character)
```

--------------------------------

### CrossPlatformService Input Handling

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/autogen/CrossPlatformService.md

This section details how to set device keys for actions and listen to input events.

```APIDOC
## CrossPlatformService Input Handling

### Description
This section covers setting up input actions for different devices and handling input events.

### Methods

#### `SetDeviceKey(device: string, key: string, action: string)`
Assigns an action to a specific key on a given device.

**Parameters:**
- `device` (string) - The device type (e.g., "Keyboard", "Mobile", "Gamepad").
- `key` (string) - The specific key or button (e.g., "Space", "JumpButton", "ButtonA").
- `action` (string) - The action to be assigned (e.g., "Up", "Collect").

**Example:**
```lua
CrossPlatformService:SetDeviceKey("Keyboard", "Space", "Up")
CrossPlatformService:SetDeviceKey("Mobile", "JumpButton", "Up")
CrossPlatformService:SetDeviceKey("Gamepad", "ButtonA", "Up")
```

#### `SetDeviceConfig(device: string, controls: Dictionary<string, string>)`
Sets the entire configuration of controls for a specific device.

**Parameters:**
- `device` (string) - The device type (e.g., "Keyboard", "Mobile", "Gamepad").
- `controls` (Dictionary<string, string>) - A table mapping keys to actions.

**Example:**
```lua
CrossPlatformService:SetDeviceConfig("Keyboard", {
	W = "Up",
	A = "Left",
	S = "Down",
	D = "Right",

	Up = "Up",
	Left = "Left",
	Down = "Down",
	Right = "Right",
	Space = "Up",
})
```

### Events

#### `InputBegin`
Fired when one of the keys/sticks in the configuration is pressed/moved.

**Parameters:**
- `inputObject` (UpsideEngineInput) - An object containing information about the input.

**Example:**
```lua
CrossPlatformService:On("InputBegin", function(inputObject)
	local character = CrossPlatformService.Character

	if inputObject.Action == "Up" then
		character:Jump(150)
	end
end)
```

#### `InputChange`
Fired when an active input changes its value (e.g., stick position).

**Parameters:**
- `inputObject` (UpsideEngineInput) - An object containing information about the input.

#### `InputEnd`
Fired when one of the keys/sticks in the configuration finishes being pressed/moved.

**Parameters:**
- `inputObject` (UpsideEngineInput) - An object containing information about the input.

```

--------------------------------

### LightingEnvironment Methods

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/autogen/LightingEnvironment.md

This section details the methods of the LightingEnvironment class, including drawing pixels and updating the screen.

```APIDOC
## LightingEnvironment Methods

### Description
Provides functionality to draw scene pixels and update screen elements.

### Methods

- **DrawPixels()** (void) - Draws the scene's pixels with the specified resolution.
- **UpdateScreen()** (void) - Updates the position, transparency, and color of the ambient light.
```

--------------------------------

### Standard Module Lifecycle Template

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/style-guide/ModuleStructure.md

A template demonstrating the required lifecycle functions for an UpsideEngine module. It includes load, start, and unload hooks to manage scene state safely.

```lua
-- imports
local exports = {}
function exports.load(scene: Scene)
	-- initialization code
end

function exports.start(scene: Scene)
	-- code to run once everything is ready
end

function exports.unload(scene: Scene)
	-- code to run before the scene is unloaded
end

return exports
```

--------------------------------

### Frequent Authority Switching in Lua

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/AuthoritySystem.md

Shows an example of a problematic pattern where authority is constantly switched between server and client. This practice leads to synchronization issues and performance degradation.

```lua
-- Server code - WRONG!
while true do
    authorityService:SetAuthority(object, "Server")
    task.wait(0.1)
    authorityService:SetAuthority(object, "Client")
    task.wait(0.1)
end
```

--------------------------------

### Map device keys to actions in Lua

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/autogen/CrossPlatformService.md

Demonstrates how to bind specific hardware keys or buttons from different devices (Keyboard, Mobile, Gamepad) to a unified action name. This allows the game logic to respond to 'Up' or 'Collect' regardless of the input device used.

```lua
-- Map movement actions
CrossPlatformService:SetDeviceKey("Keyboard", "Space", "Up")
CrossPlatformService:SetDeviceKey("Mobile", "JumpButton", "Up")
CrossPlatformService:SetDeviceKey("Gamepad", "ButtonA", "Up")

-- Map interaction actions
CrossPlatformService:SetDeviceKey("Keyboard", "E", "Collect")
CrossPlatformService:SetDeviceKey("Mobile", "JumpButton", "Collect")
CrossPlatformService:SetDeviceKey("Gamepad", "ButtonA", "Collect")
```

--------------------------------

### Add Game Background

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/get-started/FirstGame.md

Creates a standard Roblox Frame to serve as a full-screen background, setting transparency, color, and ZIndex to ensure it renders behind other game elements.

```luau
local background = Instance.new("Frame")
background.BackgroundTransparency = 0
background.BackgroundColor3 = Color3.fromRGB(27, 62, 82)
background.Size = UDim2.fromScale(1, 1)
background.Position = UDim2.fromOffset(0.5, 0.5)
background.ZIndex = -1
background.Parent = scene.Instance.Parent
```

--------------------------------

### Listen to input events in Lua

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/autogen/CrossPlatformService.md

Shows how to subscribe to input lifecycle events like 'InputBegin'. The event listener receives an input object containing the action triggered, allowing for conditional logic such as triggering a jump.

```lua
CrossPlatformService:On("InputBegin", function(inputObject)
	local character = CrossPlatformService.Character

	if inputObject.Action == "Up" then
		character:Jump(150)
	end
end)
```

--------------------------------

### Create Physical Floor Objects

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/get-started/FirstGame.md

Instantiates PhysicalObject instances to act as game floors. It configures textures, sizes, and positions using offset coordinates to ensure consistent rendering.

```luau
local leftFloor = upsideEngine.new("PhysicalObject")
leftFloor.Anchored = true
leftFloor:SetScene(scene)

local lfInstance = leftFloor.Instance
lfInstance.Image = "rbxassetid://12980969571"
lfInstance.Size = UDim2.fromOffset(600, 160)
lfInstance.Position = UDim2.fromOffset(300, 1000)

local rightFloor = upsideEngine.new("PhysicalObject")
rightFloor.Anchored = true
rightFloor:SetScene(scene)

local rfInstance = rightFloor.Instance
rfInstance.Image = "rbxassetid://12980969571"
rfInstance.Size = UDim2.fromOffset(600, 160)
rfInstance.Position = UDim2.fromOffset(1620, 1000)
```

--------------------------------

### Character Module Implementation

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/style-guide/ModuleStructure.md

A practical implementation of a character module using the UpsideEngine lifecycle. It demonstrates initializing character assets in load, handling game logic in start, and cleaning up connections in unload.

```luau
local replicatedStorage = game:GetService("ReplicatedStorage")
local runService = game:GetService("RunService")
local packages = replicatedStorage:WaitForChild("packages")

local upsideEngine = require(packages.UpsideEngine)
local crossPlatformService = upsideEngine.GetService("CrossPlatformService")

local exports = {}
function exports.load(scene: Scene)
    local character = upsideEngine.new("Character")
    character.JumpPower = 100
    character:SetScene(scene)
    character:SetSpriteSheet("idle", "rbxassetid://12908048527", Vector2.new(12, 1))
    character:SetSpriteSheet("right", "rbxassetid://12908048527", Vector2.new(12, 1))
    character:SetSpriteSheet("jump", "rbxassetid://12908048527", Vector2.new(12, 1))
    character:SetSpriteSheet("left", "rbxassetid://12970115106", Vector2.new(12, 1))
    
    local plrInstance = character.Instance
    plrInstance.ZIndex = 2
    plrInstance.ImageRectSize = Vector2.new(37, 64)
    plrInstance.Size = UDim2.fromOffset(100, 100)
    
    crossPlatformService:SetPlayerCharacter(character)
    scene.Camera:SetSubject(character)
    
    character:Play("idle")
    exports.character = character
end

function exports.start(scene: Scene)
    local spawnPosition = UDim2.fromOffset(350, 800)
    local character = exports.character
    local instance = character.Instance

    -- Avoid infinite fall
    exports.connection = runService.Heartbeat:Connect(function()
        local yPosition = instance.Position.Y.Offset
        if yPosition >= 1000 then
            instance.Position = spawnPosition
        end
    end)
end

function exports.unload()
    exports.connection:Disconnect()
end

return exports
```

--------------------------------

### BaseClass Methods

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/BaseClass.md

Documentation for the methods of the BaseClass, such as new(), IsA(), SetName(), and Destroy().

```APIDOC
## BaseClass Methods

### Description
Methods available for interacting with BaseClass objects.

### Methods

- **new()**
  Creates a new object.
  ### Request Example
  ```lua
  BaseClass.new()
  ```

- **IsA(className: string)**
  Returns true if the Instance's class is equivalent to or a subclass of a given class name.
  ### Parameters
  #### Path Parameters
  - **className** (string) - Required - The name of the class to check against.
  ### Response
  #### Success Response (200)
  - **boolean** (boolean) - True if the object is of the specified class or a subclass, false otherwise.

- **SetName(name: string)**
  Sets the object name.
  ### Parameters
  #### Path Parameters
  - **name** (string) - Required - The new name for the object.

- **Destroy()**
  Destroys the object.
```

--------------------------------

### Create and Configure Spotlight in UpsideEngine (Lua)

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/lighting-guide/Spotlight.md

This snippet demonstrates how to create a new spotlight object using UpsideEngine, set its scene, define its shape as 'spotlight', adjust its range and angle for beam focus, and set its color. It also includes an event listener for continuous rotation and mouse following.

```lua
local spotlight = UpsideEngine.new("Light")  
spotlight:SetScene(scene)  
spotlight.Shape = "spotlight"               -- Set the light's shape to "spotlight" to simulate
                                            -- a directional beam.
spotlight.Range = 500  
spotlight.Angle = 100                       -- Set the angle (in degrees) of the spotlight's beam
                                            -- smaller angle results in a narrower, more focused beam.
spotlight.Color = Color3.fromRGB(0, 0, 255)  

RunService.Heartbeat:Connect(function(dt)  
    spotlight.Instance.Position = UDim2.fromOffset(mouse.X, mouse.Y)  
    spotlight.Rotation = spotlight.Rotation + 100 * dt -- Rotate the spotlight continuously  
end)  
```

--------------------------------

### Server Temporarily Taking Control for Knockback

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/AuthoritySystem.md

Provides a server-side function example for temporarily taking 'Server' authority over a character to apply effects like knockback. After the effect, control is returned to the client.

```lua
-- Server code
local function applyKnockback(character, force)
    -- Take temporary control
    authorityService:SetAuthority(character, "Server")
    
    -- Apply physics force
    character:ApplyForce(force)
    
    -- Let physics settle
    task.wait(0.5)
    
    -- Give control back to client
    authorityService:SetAuthority(character, "Client")
end
```

--------------------------------

### Define Raycast2DParams structure in Lua

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/datatypes/Raycast2DParams.md

Defines the configuration table for raycasting, specifying the filter mode, start and end coordinates, and the list of objects to be processed. This structure is used to configure the behavior of raycast operations within the engine.

```lua
{
    FilterType = "Whitelist", -- Whitelist/Blacklist
    From = Vector2.new(),
    To = Vector2.new(),
    List = { ... } -- Dictionary<objectID, object>
}
```

--------------------------------

### Create New Object with BaseClass.new() - Lua

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/BaseClass.md

Demonstrates how to create a new object using the BaseClass.new() constructor. This is the standard way to instantiate objects derived from BaseClass.

```lua
BaseClass.new()
```

--------------------------------

### Server Managing Player Character Authority

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/replication-guide/AuthoritySystem.md

Example of server-side code that grants 'Client' authority to 'Character' objects upon receiving a replication request. This enables players to control their own characters, ensuring smooth synchronization.

```lua
-- Server code
networkingService:On("ReplicationRequest", function(request)
    if request.Content.ClassName == "Character" then
        local character = request:Accept()
        -- Give control back to the client
        authorityService:SetAuthority(character, "Client")
    end
end)
```

--------------------------------

### StaticObject Methods

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/autogen/StaticObject.md

Methods available for configuring and manipulating StaticObject instances.

```APIDOC
## SetScene

### Description
Sets the scene context for the object.

### Method
VOID

### Parameters
- **scene** (Scene) - Required - The scene instance to assign.

---

## SetShader

### Description
Assigns a custom shader to the object.

### Method
VOID

### Parameters
- **shader** (Shader) - Required - The shader instance to apply.

---

## Load

### Description
Loads an image from a URL and applies it to the object instance.

### Method
VOID

### Parameters
- **url** (string) - Required - The web URL of the image to load.

---

## SetChromaticAberration

### Description
Configures the chromatic aberration effect for the object. Set intensity to 0 to disable.

### Method
VOID

### Parameters
- **Intensity** (number) - Required - The strength of the effect.
- **Distance** (number) - Required - The distance offset for the effect.
- **Point** (Vector2) - Required - The reference point for the aberration center.
```

--------------------------------

### Instantiate Engine Classes

Source: https://github.com/notreux/upsideengine/blob/docs/docs/documentation/UpsideEngine.md

The new method allows for the dynamic creation of engine-specific objects such as Scenes, Particles, or PhysicalObjects. It requires a string argument representing the class name to be initialized.

```lua
local scene = UpsideEngine:new("Scene")
local light = UpsideEngine:new("Light")
local player = UpsideEngine:new("Character")
```

--------------------------------

### Implement Falling Platform Logic in Lua

Source: https://github.com/notreux/upsideengine/blob/docs/docs/tutorials/get-started/FirstGame.md

This script defines a function to create a physical platform that reacts to character collisions. It utilizes mass manipulation to simulate falling and TweenService to return the platform to its original position after a delay.

```lua
-- Create platform object and set properties
local function createPlatform(x, y)
	local position = UDim2.fromOffset(x, y)
	local platform = upsideEngine.new("PhysicalObject")
	platform:SetScene(scene)
	platform.Mass = 0
	platform.Anchored = false

	local platInstance = platform.Instance
	platInstance.Image = "rbxassetid://12979703349"
	platInstance.Size = UDim2.fromOffset(250, 80)
	platInstance.Position = position
	platInstance.ZIndex = 2

	-- Create Tween to animate platform to its original position on collision
	local info = TweenInfo.new(1)
	local goal = { Position = position }

	local toOrigin = tweenService:Create(platform.Instance, info, goal)
	local falling = false
	toOrigin.Completed:Connect(function()
		falling = false
	end)

	-- Listen to the "Collision" event
	platform:On("Collision", function(object) -- Create a function to detect when the plaform collides
		if not object:IsA("Character") or falling then
			return
		end

		task.wait(1)
		falling = true
		platform.Mass = 200

		task.wait(5)
		platform.Mass = 0
		platform.Force = Vector2.zero

		toOrigin:Play()
	end)
end

createPlatform(800, 900)
createPlatform(1120, 900)

for _, scr in script:GetChildren() do
	require(scr) --Initializate the secondary scripts
end
```