A sophisticated grid-based content management system for FiveM that enables efficient loading and unloading of game content based on player proximity. This system divides the game world into grids and dynamically manages content (NPCs, objects, bigdata, etc.) within each grid.

• Overview
• Features
• Installation
• Configuration
• Grid System
• Content System
• Policies
• Examples
• API Reference
• Debug Features
• License

Grid System provides a lightweight framework for managing game content efficiently by:

• Dividing the world into grid cells
• Loading content only when players are in surrounding cells
• Automatically unloading content when players leave the area
• Supporting custom content types with different behaviors
• Providing persistence options for permanent content

• Dynamic Grid Management: Automatic player tracking across grid cells
• Content Type System: Flexible content registration with customizable policies
• Client/Server Logic: Content can be processed on either client or server side
• Persistence Options: Temporary or database-stored content
• Debug Visualization: Visual grid boundaries and content information
• Permission System: Owner-only deletion and server-only content handling
• ImGUI Integration: Built-in debug interface using itIsMaku/five-imgui

1. Download and place the resource in your FiveM resources folder
2. Ensure you have mysql-async or oxmysql installed and configured
3. Add ensure maku_grid to your server.cfg

• mysql-async or oxmysql - For database operations
• FXServer with Lua 5.4 support

Edit config.lua to customize the grid system:

Config = {
    Debug = false,        -- Enable debug mode with visual grid display
    GridSize = 350.0,     -- Size of each grid cell in game units
}

The world is divided into square grid cells of configurable size (default 350 units). Each grid is identified by coordinates (e.g., "0:0", "1:-1").

-- Get grid coordinates from world position
local gridX, gridY = exports.maku_grid:getGridCoordinates(coordsX, coordsY)

-- Get grid ID from coordinates
local gridId = exports.maku_grid:getGridId(gridX, gridY)

-- Get grid ID directly from position
local gridId = exports.maku_grid:getGridIdFromPosition(coordsX, coordsY)

-- Get surrounding grid IDs (3x3 area)
local surroundingGrids = exports.maku_grid:getSurroundingGridIds(gridX, gridY)

Content types define how content will be handled after creating or deleting. Each type has specific policies that control its behavior.

-- Register a new content type
exports.maku_grid:registerContentType('your_content_type', {
    POLICIES.LOGIC.CLIENT,           -- Process on client
    POLICIES.PERSISTENCE.STORAGE,    -- Store in database
    POLICIES.HANDLE.NONE             -- Allow both client and server manipulate with data through events
})

Define how content is loaded and unloaded:

-- Client-side loading logic
exports.maku_grid:setContentLoadLogic('your_content_type', function(gridId, contentType, content, playerId)
    -- Your loading code here
    local entity = CreatePed(...)

    return true, { entity = entity } -- Return success and data
end)

-- Client-side unloading logic
exports.maku_grid:setContentUnloadLogic('your_content_type', function(gridId, contentType, content, playerId)
    -- Your unloading code here
    if content.data and content.data.entity then
        DeleteEntity(content.data.entity)
        return true
    end

    return false
end)

Policies control how content types behave:

• POLICIES.LOGIC.SERVER - Content logic runs on server
• POLICIES.LOGIC.CLIENT - Content logic runs on client

• POLICIES.HANDLE.NONE - Both client and server can manage content
• POLICIES.HANDLE.SERVER_ONLY - Only server can add/remove content

• POLICIES.PERSISTENCE.STORAGE - Content is saved to database
• POLICIES.PERSISTENCE.TEMPORARY - Content is disappears on resource restart

• POLICIES.REMOVE.OWNER_ONLY - Only content owner can delete it

• NPC Content Type
• Houses Data Content Type

-- Add content to a grid
TriggerEvent('maku_grid:addContent', gridId, contentType, content)

-- Remove content from a grid
TriggerEvent('maku_grid:removeContent', gridId, contentType, contentId)

-- Triggered when player moves to new grid
RegisterNetEvent('maku_grid:updatePlayerGrid', function(gridId, content)
    -- Handle grid change
end)

-- Triggered when content is added to nearby grid
RegisterNetEvent('maku_grid:addContent', function(gridId, contentType, content)
    -- Handle content addition
end)

-- Triggered when content is removed from nearby grid
RegisterNetEvent('maku_grid:removeContent', function(gridId, contentType, contentId)
    -- Handle content removal
end)

-- Add content to a grid
TriggerServerEvent('maku_grid:addContent', gridId, contentType, content)

-- Remove content from a grid
TriggerServerEvent('maku_grid:removeContent', gridId, contentType, contentId)

-- Server exports
exports.maku_grid:addContentToGrid(gridId, contentType, content)
exports.maku_grid:removeContentFromGrid(gridId, contentType, contentId)
exports.maku_grid:getGridContent(gridId, contentType)
exports.maku_grid:getPlayersInGrid(gridId)

-- Shared exports
exports.maku_grid:registerContentType(contentType, policies)
exports.maku_grid:setContentLoadLogic(contentType, logic)
exports.maku_grid:setContentUnloadLogic(contentType, logic)
exports.maku_grid:getRegisteredContent(contentType)

-- Get local internal client data for specific content
local data = exports.maku_grid:getLocalInternalData(gridId, contentType, contentId)

-- Get current player grid (server)
local gridId = exports.maku_grid:getPlayerGrid(playerId)

Set Config.Debug = true to enable:

• Visual grid boundaries drawn in the world
• Current grid highlighting in green
• Debug GUI showing grid information

• Z key - Toggle itIsMaku/five-imgui focus mode for GUI interaction
• When debug is enabled, a GUI window shows current grid ID and data

The debug interface displays:

• Current grid ID
• Grid data in JSON format
• Real-time updates as you move between grids

The system creates a grid table with the following structure:

CREATE TABLE `grid` (
    `grid_id` VARCHAR(50) NOT NULL,
    `content_id` INT NOT NULL AUTO_INCREMENT,
    `content_type` VARCHAR(50) NOT NULL,
    `content` LONGTEXT NOT NULL,
    PRIMARY KEY (`content_id`)
);

The system includes itIsMaku/five-imgui for debug interfaces:

• Built-in GUI components (text, buttons, inputs, etc.)
• Window management
• Real-time updates
• Mouse and keyboard interaction

1. Player Tracking: Server continuously monitors player positions
2. Grid Assignment: Players are assigned to grids based on their coordinates
3. Content Loading: When entering a new grid, surrounding content is loaded
4. Content Unloading: When leaving a grid, content is unloaded for player
5. Persistence: Content marked for storage is saved to/loaded from database
6. Synchronization: Client and server stay synchronized through events

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client Side   │    │   Server Side   │    │    Database     │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│ • Grid Logic    │◄──►│ • Player Track  │◄──►│ • Content Store │
│ • Content Load  │    │ • Grid Manage   │    │ • Persistence   │
│ • ImGUI Debug   │    │ • Content Sync  │    │                 │
│                 │    │ • Database I/O  │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0).

You are free to:

• Use, copy, modify, and distribute this project and derivative works

Under the following conditions:

1. Attribution: Credit the original author (Adam Volkman) and repository
2. Public Availability: Modified versions must remain publicly accessible
3. License Notice: Include this license in copies

For more details, see the LICENSE file.

Adam Volkman (itismaku)

• Discord: itismaku (maku#5434)
• GitHub: itIsMaku