Dynamic Billboard Advertising

All settings live in rs_ad_agency/shared/config.lua, in the AgencyConfig table. The examples below use the existing defaults. Change the matching fields in your full configuration instead of replacing whole tables with shortened examples.

Note

Every setting can also be changed in game, in the admin panel’s Settings tab (/adagencyadmin), with an explanation on hover. Changes made there apply live, are saved in the database, and take priority over config.lua. Reset returns a setting to its file value. Rendering, house ad, model, framework, and keybind settings apply after restart rs_ad_agency.

---

General Settings

config.lua

AgencyConfig.Debug = false
AgencyConfig.OpenTestAccess = false
AgencyConfig.AdminAce = 'command.rsadagency'

Option	Description
AgencyConfig.Debug	Additional diagnostic output; normally false on live servers
AgencyConfig.OpenTestAccess	Test mode: every player is an admin and rentals are free. Private test servers only
AgencyConfig.AdminAce	The ACE that marks a player as an agency admin

Access Points and Interaction

config.lua

AgencyConfig.Access = {
Points = 'both',          -- kiosk | npc | both
Interaction = 'auto',     -- key | target | auto
TargetResource = 'auto',  -- auto | ox_target | qb-target
TargetDistance = 2.5,
KioskLabel = 'Rent a billboard',
AgentLabel = 'Talk to the Ad Agency rep',
}

Points chooses how players reach the agency: the touchscreen kiosk, the NPC rep, or both. With Interaction = 'auto', the script uses your target resource when ox_target or qb-target is running, and the Press E prompt otherwise.

---

Agency Kiosks

config.lua — kiosk fields

AgencyConfig.Kiosk.Enabled = true
AgencyConfig.Kiosk.Model = 'rs_ad_agency_kiosk'
AgencyConfig.Kiosk.SpawnDistance = 120.0
AgencyConfig.Kiosk.InteractDistance = 1.6
AgencyConfig.Kiosk.ScreenDistance = 30.0
AgencyConfig.Kiosk.WatchDistance = 25.0
AgencyConfig.Kiosk.MaxWatchers = 24
AgencyConfig.Kiosk.PreviewControl = 74 -- H
AgencyConfig.Kiosk.Locations = {}

Setting	Default	What it controls
SpawnDistance	120.0	Distance at which the kiosk prop appears
InteractDistance	1.6	How close a player must stand to use the kiosk
ScreenDistance	30.0	Distance at which the kiosk screen comes alive
WatchDistance	25.0	Players this close watch a kiosk session live (OneSync)
MaxWatchers	24	Most players watching one kiosk at once
PreviewControl	74	Key that previews the ad on the billboard while editing (74 = H)

Kiosks are normally placed in game with /rsad_kiosk place and saved in the database. Fixed kiosks can also be listed in Locations.

Starter Kiosks

AgencyConfig.Kiosk.StarterLocations holds six kiosks (Rockford Hills, Maze Bank Arena, Tataviam, Harmony, Paleto Bay, and Chumash). They are placed once, on the first start with a new database, as ordinary placed kiosks. Admins can move or remove them in game, and removed ones never come back. Empty this list before the first start to begin with no kiosks.

Agency Reps

config.lua — rep fields

AgencyConfig.AgencyAgent.Enabled = true
AgencyConfig.AgencyAgent.Model = 'a_m_y_business_01'
AgencyConfig.AgencyAgent.Scenario = 'WORLD_HUMAN_CLIPBOARD'
AgencyConfig.AgencyAgent.SpawnDistance = 60.0
AgencyConfig.AgencyAgent.InteractDistance = 2.2
AgencyConfig.AgencyAgent.Locations = {}

Talking to a rep opens the same agency manager as a kiosk, so the agency works anywhere without a kiosk prop. Reps are placed in game with /rsad_npc place; fixed ones can be added to Locations.

---

Rental Terms and Payment

config.lua — rental block

AgencyConfig.DefaultBasePrice = 500

AgencyConfig.Rental = {
Terms = {
  [1]  = { key = 'day',   label = '1 day',   price_multiplier = 1.0 },
  [7]  = { key = 'week',  label = '7 days',  price_multiplier = 6.0 },
  [30] = { key = 'month', label = '30 days', price_multiplier = 24.0 },
},
PaymentAccount = 'bank', -- bank | cash | crypto
AllowUnchargedStandalone = false,
}

Each board has a daily base price (DefaultBasePrice unless changed for that board in the admin panel). A term multiplies it. With the defaults and no traffic, a board costs:

Term	Multiplier	Price
1 day	1.0	$500
7 days	6.0	$3,000
30 days	24.0	$12,000

PaymentAccount selects the framework account rent is taken from. crypto works with Qbox and QBCore; ESX has no crypto account, so renting is refused rather than charging another account. AllowUnchargedStandalone = true lets servers without a framework rent for free.

Note

Prices are calculated and validated by the server. The agency manager only previews them.

Slides

config.lua

AgencyConfig.Slides = {
Max = 5,
ExtraSlidePercent = 0.25,
}

A rental includes one slide. Each extra slide adds ExtraSlidePercent of the rental price (0.25 = +25% per slide), up to Max slides that rotate on the board. Slides are chosen when renting; adding one later in the editor charges its share for the time left on the rental.

Traffic-Based Pricing

config.lua

AgencyConfig.AnalyticsViewDistance = 100.0
AgencyConfig.AnalyticsViewCooldownMs = 1800000 -- 30 minutes
AgencyConfig.TrafficViewsPerPriceStep = 25
AgencyConfig.TrafficPriceStep = 0.10
AgencyConfig.TrafficMaxMultiplier = 3.0

A player within AnalyticsViewDistance of a board counts as a view, and is counted again for the same board only after the cooldown. Every TrafficViewsPerPriceStep views in the last 7 days add TrafficPriceStep to the board’s price, up to TrafficMaxMultiplier.

How rent is calculated

rent = daily base price
   × traffic multiplier       -- 1.0 up to 3.0
   × term multiplier          -- 1.0, 6.0 or 24.0
   × (1 + extra slides × 0.25)

---

House Ads

config.lua

AgencyConfig.HouseAds = {
Count = 50,
Brand = 'AD NAUSEAM',
VariantsPerBucket = 3,
}
AgencyConfig.DecalRenderer.BakedHouseAds = true

Unrented boards show the built-in Ad Nauseam house ads. VariantsPerBucket sets how many different house ads appear per board shape; each distinct ad on screen uses one render slot, so lower it if boards start popping in dense areas. Keep BakedHouseAds = true: unrented boards then use pre-baked textures and cost almost nothing to render.

Ad Size Limits

config.lua

AgencyConfig.MaxAdAssetBytes = 32 * 1024 * 1024
AgencyConfig.MaxAdDesignBytes = 750 * 1024

Setting	Default	What it controls
MaxAdAssetBytes	32 MB	Largest media file an ad can use
MaxAdDesignBytes	750 KB	Largest saved ad design

Rendering and Performance

config.lua — selected defaults

AgencyConfig.RenderDistance = 275.0
AgencyConfig.RenderMaxVisiblePanels = 96
AgencyConfig.PanelResolution = { width = 1024, height = 1024 }
AgencyConfig.PanelResolutionMin = 256
AgencyConfig.PanelResolutionMax = 2048
AgencyConfig.DecalRenderer.MaxLiveCreatives = 55
AgencyConfig.DecalRenderer.AddMaxDistance = 250.0

Only boards near the player render. AddMaxDistance is the range at which an ad is placed on a board, and RenderDistance the range at which it is kept. MaxLiveCreatives is the number of different ads that can be on screen at once, and RenderMaxVisiblePanels the number of boards.

Caution

These limits balance quality, ad count, and client performance. Raising them can add significant rendering and memory cost. Test changes in a dense area such as Vinewood with several players before using them live. They apply after restart rs_ad_agency.

Permissions

config.lua

AgencyConfig.AdminAce = 'command.rsadagency'

AgencyConfig.Framework = {
qbPermissions = { 'god', 'admin' },
qboxGroups = { 'god', 'admin' },
esxGroups = { 'superadmin', 'admin' },
}

A player is an agency admin with the AdminAce, the general command ACE, or one of the listed framework groups. For a different staff system, adapt AgencyServer.isAdmin in server/bridge.lua (see Development).

Map Blips

config.lua

AgencyConfig.Kiosk.Blip = {
Enabled = true, sprite = 605, color = 46, scale = 0.75,
shortRange = true, label = 'Ad Agency Kiosk',
}
AgencyConfig.AgencyAgent.Blip = {
Enabled = true, sprite = 605, color = 46, scale = 0.8, shortRange = true,
}

Every kiosk and rep gets a map blip. Set Enabled = false to hide them, or set label = nil on the kiosk blip to use each kiosk’s own label.