Developer Preview

Menus & dialogs

Ready-made menus, context menus, notifications, progress bars and dialogs.

Developer Preview. Scripting is live on Neighborly servers – everything on these pages works today. The API is young, so tell us what you need next on Discord.

Not every UI needs your own HTML. The built-in neighborly resource gives you menus, context menus, notifications, progress bars and dialogs that already look like Neighborly and work with mouse, keyboard and controller. They are all client exports.

openMenu shows a list menu at the side of the screen. Each item can run a function, open another menu or just show information.

void exports.neighborly:openMenu(table menu)
FieldTypeDescription
idstringUnique id. Opening a menu with the same id replaces it.
titlestringHeading at the top.
subtitlestring?Smaller line under the title.
positionstring?'right' (default), 'left' or 'center'.
itemstableList of items: label, description, icon, badge, disabled, value, onSelect(item), submenu (another menu table).
onClosefunction?Called when the player closes the menu with Esc or the close button.
client.luaLUA
local function openGarden()
    exports.neighborly:openMenu({
        id = 'garden_shop',
        title = 'Garden Shop',
        subtitle = 'Seeds for every season',
        items = {
            {
                label = 'Tomato seeds',
                description = 'Grows in spring and summer',
                icon = 'plant',
                badge = '§15',
                onSelect = function()
                    TriggerServerEvent('garden:buy', 'tomato')
                end
            },
            {
                label = 'Rare seeds',
                icon = 'star',
                submenu = {
                    id = 'garden_rare',
                    title = 'Rare seeds',
                    items = {
                        { label = 'Dragonfruit', badge = '§120', value = 'dragonfruit' },
                        { label = 'Cowplant berry', disabled = true, description = 'Sold out' }
                    }
                }
            }
        },
        onClose = function()
            print('Shop closed')
        end
    })
end

RegisterCommand('garden', openGarden, false)

Close any open menu with exports.neighborly:closeMenu().

Context menus

Context menus are small floating menus. Register them once with an id, then show them by id whenever you need them – for example from a command or a key mapping. Options can call a function, trigger a client event or trigger a server event directly.

client.luaLUA
exports.neighborly:registerContext({
    id = 'cafe_register',
    title = 'Cash register',
    options = {
        { title = 'Clock in', icon = 'clock', serverEvent = 'rtx_cafe:clockIn' },
        { title = 'Clock out', icon = 'door', serverEvent = 'rtx_cafe:clockOut' },
        { title = 'Today\'s earnings', icon = 'money', event = 'rtx_cafe:showEarnings', args = { day = 'today' } },
        { title = 'Manager tools', icon = 'gear', menu = 'cafe_manager' }
    }
})

exports.neighborly:registerContext({
    id = 'cafe_manager',
    title = 'Manager tools',
    menu = 'cafe_register',
    options = {
        {
            title = 'Change prices',
            onSelect = function()
                TriggerEvent('rtx_cafe:openPriceEditor')
            end
        }
    }
})

exports.neighborly:showContext('cafe_register')

Notifications

notify shows a Neighborly toast in the top right corner. From the server, send the same table with the neighborly:notify event.

void exports.neighborly:notify(table data)
FieldTypeDescription
titlestring?Bold first line.
textstringThe message.
typestring?'info' (default), 'success', 'warning' or 'error' – sets color and sound.
iconstring?Icon name, replaces the default icon of the type.
durationnumber?Milliseconds on screen, default 5000.
client.luaLUA
exports.neighborly:notify({
    title = 'Order up!',
    text = 'Your latte is ready at the counter.',
    type = 'success',
    icon = 'coffee'
})
server.luaLUA
TriggerClientEvent('neighborly:notify', source, {
    title = 'Bill paid',
    text = 'Water bill: §85',
    type = 'info'
})

notify is the light Neighborly toast. The ShowNotification native instead posts a real Sims 4 notification with a Sim's portrait that stays in the game's notification history – use it for story moments.

Progress bars

progressBar shows a bar and waits until it finishes. It returns true when completed and false when the player cancelled. Pair it with PushSimInteraction if the Sim should do something while the bar fills. Because it waits, call it inside a thread, event handler or callback (they all run as threads).

client.luaLUA
local done = exports.neighborly:progressBar({
    label = 'Brewing espresso...',
    duration = 6000,
    canCancel = true
})

if done then
    TriggerServerEvent('rtx_cafe:brewed')
else
    exports.neighborly:notify({ text = 'You stopped brewing.', type = 'warning' })
end

Input dialogs

inputDialog(title, rows) asks the player for one or more values and returns them as a list in the same order, or nil if they cancelled. Row types: input, textarea, number, slider, select, checkbox, color, date.

client.luaLUA
local values = exports.neighborly:inputDialog('Open a tab', {
    { type = 'input', label = 'Customer name', required = true },
    { type = 'number', label = 'Amount', min = 1, max = 5000, default = 25 },
    { type = 'select', label = 'Payment', options = {
        { value = 'cash', label = 'Cash' },
        { value = 'card', label = 'Card' }
    } },
    { type = 'checkbox', label = 'Add a tip' }
})

if values then
    TriggerServerEvent('rtx_cafe:openTab', values[1], values[2], values[3], values[4])
end

Alert dialogs

alertDialog asks a yes/no question and returns 'confirm' or 'cancel'.

client.luaLUA
local answer = exports.neighborly:alertDialog({
    header = 'Sell your home?',
    content = 'You will receive §48,000 and your household moves out.',
    confirmLabel = 'Sell',
    cancelLabel = 'Keep it'
})

if answer == 'confirm' then
    TriggerServerEvent('realty:sellHome')
end

Text hints

showTextUI(text, options) pins a small hint on screen until you call hideTextUI() – handy while a player stands near something.

client.luaLUA
AddEventHandler('lotEntered', function(zoneId)
    if zoneId == Config.CafeLot then
        exports.neighborly:showTextUI('Welcome to Bluejay Café – click the register to clock in', { icon = 'coffee' })
    end
end)

AddEventHandler('lotLeft', function(zoneId)
    if zoneId == Config.CafeLot then
        exports.neighborly:hideTextUI()
    end
end)