Garry's Mod Wiki

VGUI Creating Custom Elements

Why Create Custom VGUI Elements?

Creating custom VGUI elements helps with many things, the biggest being code readability and maintainability. These new elements don't always have to be some brand new element from the ground up, in fact many custom elements are just derivatives from the games base panels with customizations that fit that project better.

Think of something like a DButton the default styling may not suit the look and feel of your project, so instead of having to restyle every DButton you create, you can create a new custom VGUI element that is derived from the standard DButton. Then apply your styling to that the new element once. This means that each time you create this new custom element you wont need to reapply the same styling, you'll only need to add what makes that button unique.

Now you could create panels in the same file you want to use them with vgui.CreateFromTable however using this method to create panels usually leads to a very long file that becomes hard to read and maintain once your no longer activity working on it. Therefor while acceptable under specific circumstances this shouldn't be the main way of creating your custom elements.

Creating Custom Elements

The first and most fundamental thing you should know about any Panel is that it consists of four fundamental components:

There are other hooks available like the PANEL:Think hook, but this is not required the panel to operate. Also some hooks are only available to specific panels, and for the sake of simplicity we will skip over those here and just point you to PANEL_Hooks to see all the hooks available to panels.

Setting up your workspace

Hopefully you have a basic understanding of the filesystem in Garry's Mod but as a crash course, all you need to know is that everything included in your addon folder gets """merged""" with the existing folder structure in your copy of the game. Now these don't actually move any files around, but its important to remember that the engine sees your *myAddonName*/lua/autorun/client/example.lua in the same spot as: *garrysmod*/lua/autorun/client/example.lua

I wanted to emphasis that because we will be leveraging that functionality to help organize our custom VGUI elements. Using the Lua Folder Structure we can see that there is lua/vgui this folder is loaded whenever the game loads its VGUI elements. This means any custom VGUI elements we create for out addon will be loaded automatically when we enter the game instead of needing to manually include them in our autorun script.

Coding the new Element

Now that you understand the basics of how panels work, we can start writing out own.

to start working on a new panel create a new file under lua/vgui/{nameOfElement}.lua and make sure to write in the four fundamental elements from before like so:

-- Creating the Table our panel will use PANEL = PANEL or {} --Creating our Init Function function PANEL:Init() end --Creating the Paint Function function PANEL:Paint() end --Registering our new VGUI element, giving it a name, the table to use, and if it derives methods from another element vgui.Register("NewElementName",PANEL,"OptionalNameOfPanelItsDerivedFrom")

Now that we the essential outline of our panel created lets start by seeing if one of the premade elements from VGUI Element List has similar functionality to what we already need. Its important to look at the methods these panels already have, for example we are going to create a custom button. So we should derive our new panel from the DButton panel since that will give us access to methods like PANEL:DoClick.

Lets do that now by updating our vgui.Register function in our code

vgui.Register("WikiButton",PANEL,"DButton")

So what exactly did that do?

All the premade panels in Garry's Mod are derived from one of the engine panels, these engine panels can be found on the VGUI Element List page. Most of the Panels that start with a "D" are derivatives of these engine panels with functionality and PANEL:Paint functions applied to them to be easier to work with.

Most of the time you will never need to derive directly from an engine panel unless your creating a whole new type of element from scratch. Instead its commonly easier to derive your panel from one the "D" Panels which gives you access to more convivence functions instead of needing to recode basic functionalities into your panel every time.

When we set our new WikiButton element to derive from the DButton we get every method that DButton has access to and everything that it also derives from. Here is a tree that shows the chain of derivatives:

Panel - Label - DLabel - DButton - WikiButton <-- this being our custom element

Using your Custom VGUI Component

Using the components you've created is the same as using any other premade element (seeing as we just created an element in the same way)

all you need is the vgui.Create function with the name you gave the vgui.Register function. for our WikiButton our create function would look like:

VarName = vgui.Create("WikiButton")
This page did not cover anything about customizing this new panel we created. This page was created to be more informative about the process of creating custom VGUI elements instead of customizing them. The wiki button mentioned in this article will look identical to a DButton because nothing in this article covered changing anything about it (yet?)