Configuration

Every setting lives in one file: config.lua in the resource's main folder. You can open it with any plain text editor. After changing it, restart the oxide-multichar resource (or your whole server) for the changes to take effect.

A note on coordinates: many settings use map coordinates. A vector4(x, y, z, w) is a position with a direction — x, y, z is where, and w is the heading (which way the character or camera faces, 0–360). A vector3(x, y, z) is a position with no direction. If you are not comfortable finding coordinates in-game, the built-in defaults work fine and you can leave most of this file alone.

Spawn Locations

Config.Spawn

Fallback spawn positions. These are used when the spawn picker is turned off, or when a character has no saved position to return to.

Config.Spawn = {
    new = vector4(-1037.71, -2737.82, 20.17, 327.53),
    useLastPosition = true,
    fallback = vector4(-1037.71, -2737.82, 20.17, 327.53),
}

Camera

Config.Camera

Controls where the camera sits during selection and creation. Each pose is a position, a rotation (the three numbers are pitch, roll, and yaw in degrees), and a field of view (fov — lower numbers zoom in, higher numbers zoom out).

The creatorPresets are what the camera buttons in the appearance editor jump to. Each one is named (fullbody, upper, face, feet) and is a complete camera pose. Tune the fov of each to frame the right part of the character.

Config.Camera = {
    selection = {
        coords = vector3(-35.52, -584.42, 83.91),
        rotation = vector3(-5.0, 0.0, 68.95),
        fov = 45.0,
    },
    creation = {
        coords = vector3(-36.52, -584.10, 84.30),
        rotation = vector3(-5.0, 0.0, 68.95),
        fov = 40.0,
    },
    creatorPresets = {
        fullbody = { coords = vector3(-36.52, -584.10, 84.30), rotation = vector3(-5.0, 0.0, 68.95), fov = 50.0 },
        upper    = { coords = vector3(-36.52, -584.10, 84.30), rotation = vector3(-3.0, 0.0, 68.95), fov = 32.0 },
        face     = { coords = vector3(-36.52, -584.10, 84.30), rotation = vector3(0.0, 0.0, 68.95),  fov = 20.0 },
        feet     = { coords = vector3(-36.52, -584.10, 84.30), rotation = vector3(-18.0, 0.0, 68.95), fov = 30.0 },
    },
}

Preview Characters

Config.PedPreview

Where the character being created stands, and the spacing used if multiple preview characters are shown.

Config.PedPreview = {
    coords = vector4(-39.07, -583.17, 84.17, 245.61),
    spacing = 1.5,
}

Hover Behavior

Config.Hover

Controls how the screen responds when a player moves the mouse over a character and clicks to select.

Config.Hover = {
    maxDistance = 100.0,
    resetFrames = 3,
    smoothing = 8.0,
    nudge = 0.1,
}

Info Card

Config.HeadCard

Tunes the floating card shown above a character's head.

Config.HeadCard = {
    heightOffset = 0.45,
    nearDist = 2.0,
    farDist = 6.0,
    scaleMin = 0.8,
    scaleMax = 1.0,
}

Create Slot

Config.CreateSlot

The dimmed "ghost" figure shown in an empty spot that players click to create a new character.

Config.CreateSlot = {
    model = 'mp_m_freemode_01',
    alpha = 130,
}

Character Management

Config.AllowDelete = true
Config.RequireDeleteConfirmation = true
Config.MaxCharacters = 5

Extra Slots for VIPs / Staff

Config.SlotGrants

This is how you give specific players more character slots than the base Config.MaxCharacters — for example, donators get 7 slots and staff get 12, while everyone else stays at 5.

A player's final slot count is the highest number they qualify for. Grants never lower the base, and they do not add together: a player who matches both a 7-slot grant and a 12-slot grant gets 12, not 19.

There are two ways to grant extra slots. You can use either or both.

1. By permission (recommended). You list a permission name and how many slots it unlocks. You then give that permission to players using your server's normal permission setup.

Config.SlotGrants = {
    ace = {
        ['multichar.vip']     = 7,
        ['multichar.vipplus'] = 10,
        ['group.admin']       = 12,
    },
    identifiers = {},
}

To hand a permission to a player or a group, add lines like these to your server.cfg (these use FiveM's built-in permission system — no extra resources needed):

# Make a "vip" group that gets the 7-slot permission
add_ace group.vip multichar.vip allow

# Put a specific player into that vip group (use their license, found in your player list)
add_principal identifier.license:abc123... group.vip

The player gets the extra slots the next time they reconnect.

2. By a specific player ID. If you just want to bump one person without setting up a group, list their identifier and the slot count directly:

Config.SlotGrants = {
    ace = {},
    identifiers = {
        ['license:abc123...'] = 8,
        ['discord:1122334455'] = 6,
    },
}

You can find a player's license: identifier in your server's player list, or in your framework's database. Any identifier your server hands out works (license:, discord:, fivem:, steam:, etc.) — it must match exactly.

Character Creation

Config.AllowCreation

Controls whether players can make new characters. Their existing characters are unaffected — they can still log in, play, and delete; they just can't create more while this is off.

Config.AllowCreation = true
Config.CreationAce = nil  -- e.g. 'multichar.create'
Config.CreationDisabledMessage = 'Character creation is currently closed.'

Two common uses:

• Pause creation for everyone (e.g. during an event or a lore wipe): set Config.AllowCreation = false. Existing players keep playing; nobody can make new characters.

• Whitelist-only creation: set Config.AllowCreation = false and set Config.CreationAce = 'multichar.create', then grant that permission to your whitelisted players in server.cfg:

  add_ace group.whitelist multichar.create allow
  add_principal identifier.license:abc123... group.whitelist

  Only players with the permission can create; everyone else sees the closed message.

Spawn Picker

Config.SpawnSelector

The sky-view screen where players choose where to spawn after picking a character.

Each preset in presets is a row with an id (an internal name with no spaces), a label (what the player sees), coords (a vector4 with heading), and optionally its own cam to hand-tune the sky view for that destination. If presets is left empty, Config.Spawn.new is used as the only public spawn.

The camera.focus block is not a camera position but a recipe: height meters above the target, back meters south of it, pitched down by pitch degrees, at the given fov.

Config.SpawnSelector = {
    enabled = true,
    allowLastLocation = true,

    presets = {
        { id = 'legion',  label = 'Legion Square', coords = vector4(195.17, -933.77, 30.69, 144.0) },
        { id = 'airport', label = 'LSIA',          coords = vector4(-1037.71, -2737.82, 20.17, 327.53) },
        { id = 'paleto',  label = 'Paleto Bay',    coords = vector4(-275.93, 6635.06, 7.43, 42.0) },
    },

    markerHeight = 80.0,
    camera = {
        idle  = { coords = vector3(-200.0, -1600.0, 1000.0), rotation = vector3(-42.0, 0.0, 0.0), fov = 60.0 },
        focus = { height = 220.0, back = 90.0, pitch = -55.0, fov = 50.0 },
    },
}

Starter Apartment

Config.StarterApartment

A free apartment given to new characters, where the housing system supports it.

How this behaves on each housing system is explained in Features. The qb entry is only a fallback — when qb-apartments can list its apartments, the player picks one in the spawn screen instead.

Config.StarterApartment = {
    enabled = true,
    qb = { type = 'apartment1', label = 'South Rockford Drive' },
    qbx = {
        label = 'Del Perro Heights Apt',
        interior = 'DellPerroHeightsApt4',
        enter = vec3(-1447.35, -537.84, 34.74),
        interact = {
            { type = 'logout',   coords = vec3(-1454.08, -553.25, 72.84) },
            { type = 'clothing', coords = vec3(-1449.88, -549.25, 72.84) },
            { type = 'exit',     coords = vec4(-1453.02, -539.5, 74.04, 35.33) },
        },
        stash = { coords = vec3(-1466.83, -527.03, 73.44), slots = 50, maxWeight = 150000 },
    },
}

Appearance Editor

Config.CustomCreator

The built-in editor where new players design their full look.

The editor only works with supported clothing resources (oxide-identity, illenium-appearance, qb-clothing, fivem-appearance). On any other clothing resource it is skipped automatically and the native editor is used — see Features.

Config.CustomCreator = {
    enabled = true,
    allowTattoos = true,
}

Name and Age Rules

Config.NameLength

Config.AgeRange

Config.NameLength = { min = 2, max = 20 }
Config.AgeRange   = { min = 18, max = 80 }

Config.NameRules

Extra rules applied to names on top of the length and character checks above. These are checked on the server when a character is created, so they cannot be bypassed.

Config.NameRules = {
    unique = true,
    blacklist = { 'admin', 'staff', 'owner', 'moderator' },
}

Scenes

Config.Scenes

The backdrops the selection screen can be set in. This is the largest part of the config.

Scene mode controls which backdrop a player sees when the screen opens. The in-screen scene switcher still works in every mode — this only sets the starting scene.

Each entry in list describes one scene:

To add a scene, copy an existing entry, give it a new key, and adjust the camera, standing spots, weather, and time. To remove one, delete its entry (and make sure Config.Scenes.default doesn't point at it). The weather and time changes only affect the player viewing the screen — they do not change the live server world.

Config.Scenes = {
    mode = 'saved',         -- 'saved' | 'random' | 'default'
    default = 'apartment',
    list = {
        apartment = {
            name = 'Apartment',
            cam = { coords = vector3(-784.7750, 340.0801, 211.3950), rotation = vector3(0.682074, 0.0, 224.007968), fov = 43.0 },
            ped = { coords = vector4(-781.3235, 336.4592, 210.1991, 355.3351), animation = { dict = 'timetable@ron@ig_3_couch', name = 'base' }, fov = 25 },
            -- ped_2 ... ped_5 define additional standing spots
            vehicle = nil,
            weather = 'EXTRASUNNY',
            time = { hour = 20, minute = 0 },
        },
        -- garage, pier, sinner ...
    },
}

Logout

Config.Logout

The command that returns a player to character selection.

Config.Logout = {
    enabled = true,
    command = 'logout',
    fadeOutDuration = 500,
    holdDuration = 1500,
    fadeInDuration = 500,
}

Links

Config.Links

Config.Links = {
    discord = 'https://discord.gg/dZ6q8FyGhm',
}

Announcements

Config.Announcements

A list of news items shown on the selection screen. Each item is a row with these fields:

Edit, add, or remove entries freely. To show no announcements, set this to an empty list (Config.Announcements = {}).

Config.Announcements = {
    {
        title = 'Server Restart Tonight',
        body = 'Scheduled restart at 3 AM EST. Expect ~5 minutes of downtime.',
        type = 'info',
        date = '2026-01-24',
    },
    -- more announcements ...
}

Next Steps