Customizing Radio Frames

Customize your community's radio frames!

Video Tutorial:

Sonoran Radio: Customize Frames

Selecting Custom Frames

Custom radio frames can be selected in the radio settings menu. Custom frames allow your community to create more UI options for each department!

The drop-down menu will appear in your settings menu if you have one or more options available to you.

Sonoran Radio - High Visibility Frame

Restricting Custom Frames

Restrict radio frames by department, job, or job grade, and set admin command permissions. Compatible with ESX, QBCore, or as a standalone.

You can use CMS to automatically manage in-game ACE permissions, and even sync them with Discord roles!

Example: SAHP department members with police job grades 1-3 can use frames:

• default
• signalpro
• voxguard
• hi-vis

Config.frames

Config.frames = {
	permissionMode = 'ace', -- ace, qbcore, esx or none
	adminPermission = 'sonoranradio.admin', -- ACE permission required to use admin commands
	departments = {
		['sahp'] = {
			label = 'San Andreas Highway Patrol',
			permissions = {
				jobs = { -- Jobs that can use this department
					['police'] = {
						grades = { -- Job grades that can use this department
							1,
							2,
							3
						}
					}
				},
				ace = { -- ACE Permissions that can use this department | ONLY EFFECTIVE IN ACE PERMISSION MODE
					'sonoranradio.sahp'
				}
			},
			-- Radio frames that can be used by this department
			allowedFrames = {
				'default',
				'signalpro',
				'voxguard',
				'hi-vis'
			}
		}
	}
}

Customizing Radio Frames

1. Navigate to the sonoranradio\skins directory.
2. Locate a skin folder, which will contain 2-4 images and a skin.json file, displaying different frames.
3. Observe the images, which include handheld, mobile, aircraft, and possibly HUD radio types.
4. Create a new skin folder and add your own frame images in the format you've observed in Step 3.
5. Copy over and modify an existing skin.json file to maintain format consistency.
6. In the skin.json file, specify the radio name and configure the frame types and body settings.
7. Configure the skin

   1. In the skin.json file, define the images for each radio type.
   2. Enable debug mode by setting Config.debug to true in your config.lua file.
   3. Use the in-game frame placement menu for easy adjustments.

Sonoran Radio - Vehicle Radio - Debug Mode Enabled

Frame Types

The following are valid as values for type:

• portable - Used for handheld radios
• vehicle - Used for mobile radios installed in a vehicle
• hud - Top-down view of a portable radio

With vehicle type frames, you can additionally customize the vehicleClasses property to whitelist the frame to specific vehicle types.

For example, our default skin whitelists one frame to aircraft only: "vehicleClasses": [15, 16]. See available vehicle classes here.

Body Settings

1. In body, specify the image filename for each radio type. For instance, use radio-portable.png for a portable radio.
2. Additionally, set the width value to define the image's display width in-game.

Controls

1. Assign actions to buttons at specific positions on the radio image.

   • Example: Align a panic button hitbox with the panic button on the image, so clicking it in-game triggers a panic action.
2. Available action types: power, next_preset, prev_preset, panic, home, hide.

Screen and Mini-Screen

Specify the position and width of the radio frame screen in Sonoran Radio to display information. Modify values under screen or miniScreen for HUD-type frames.

For HUD-type frames, controls can be left blank.

Screen Styles

If you would like to use a text-style display instead of the normal radio screen, you can set the style to text. For example:

"screen": {
  "style": "text",
  "bottom": 17.625,
  "height": 7.875,
  "left": 5.125,
  "right": 5.875,
  "scale": 0.65
}

Sonoran Radio Screen - Default

Sonoran Radio Screen - Text

Example File

Below is an example of a skin.json file:

skin.json

{
  "name": "Moto AX",
  "frames": [
    {
      "type": "portable",
      "body": { "image": "radio-portable.png", "width": 17 },
      "controls": [
        {
          "action": "power",
          "bottom": 29.6,
          "right": 0.8,
          "width": 2.7,
          "height": 2.7
        },
        {
          "action": "next_preset",
          "bottom": 30,
          "right": 7.25,
          "width": 1.25,
          "height": 4.25
        },
        {
          "action": "prev_preset",
          "bottom": 30,
          "left": 7.125,
          "width": 1.25,
          "height": 4.25
        },
        {
          "action": "panic",
          "bottom": 29.75,
          "left": 4,
          "width": 2,
          "height": 1.25
        },
        {
          "action": "home",
          "bottom": 3.25,
          "left": 6.75,
          "right": 6.75,
          "height": 1.5
        }
      ],
      "screen": {
        "bottom": 5.875,
        "height": 18.125,
        "left": 3.2185,
        "right": 3.2,
        "zIndex": 5
      }
    },
    {
      "type": "vehicle",
      "body": { "image": "radio-mobile.png", "width": 45.125 },
      "controls": [
        {
          "action": "power",
          "top": 2.25,
          "left": 6.15,
          "width": 2,
          "height": 2
        },
        {
          "action": "prev_preset",
          "top": 2.25,
          "right": 17.25,
          "width": 1.5,
          "height": 2
        },
        {
          "action": "next_preset",
          "top": 5,
          "right": 17.25,
          "width": 1.5,
          "height": 2
        },
        {
          "action": "hide",
          "top": 8.25,
          "right": 17.25,
          "width": 1.5,
          "height": 1.5
        },
        {
          "action": "home",
          "top": 11.25,
          "right": 17.25,
          "width": 1.5,
          "height": 1.5
        },
        {
          "action": "panic",
          "top": 2.25,
          "right": 3.75,
          "width": 2,
          "height": 2
        }
      ],
      "screen": {
        "top": 2.65,
        "height": 10.2,
        "left": 11,
        "width": 13.45,
        "zIndex": 5
      }
    },
    {
      "type": "hud",
      "body": { "image": "radio-portable-top.png", "width": 22.25 },
      "controls": [],
      "miniScreen": {
        "bottom": 7.2,
        "height": 3.75,
        "left": 7.75,
        "right": 7.5
      }
    }
  ]
}

Frame Placement Menu

The frame placement menu offers rapid configuration of the screen size, location, and button placements.

With debug mode enabled, open the menu by clicking on the icon in the top right of your screen.

Select the skin ID and frame that you wish to edit. Then, select each property and utilize the arrow keys to adjust the configuration.

Once complete, save your changes using the Save skin.json button.

Programmatically Changing Frames

To get all available frames, utilize the following server-side export:

local frames = exports.sonoranradio:GetAvailableFrames(GetResourcePath('sonoranradio').. '/skins')
print(json.encode(frames))
-- Returns:
-- ["default","hi-vis","signalpro","voxguard"]
-- Array of frame names 

To set a users frame, utilize the client-side event:

local frameName = "hi-vis" -- Frame/skin name | i.e. hi-vis, default, voxguard
local source = 1 -- User's server ID
TriggerClientEvent('SonoranRadio::AdminSkinChange', source, frameName)