Jump to content
  • Advertisement
  • 12/02/18 10:30 PM

    How to Implement Custom UI Meshes in Unity

    Engines and Middleware

    Christopher Mielack

    You want to create custom meshes for your Unity3D UI, but you found the documentation lacking?

    In this article, I will describe

    • How to implement a bare-essentials custom Unity UI mesh
    • Point out all the pitfalls that leave you looking at invisible or non-existent meshes



    • To implement your own UI mesh, derive from MaskableGraphic and implement OnPopulateMesh().
    • Don’t forget to call SetVerticesDirty/SetMaterialDirty upon changes to texture or other editor-settable properties that influence your UI-elements and should trigger a re-rendering.
    • Don’t forget to set the UIVertex’s color, otherwise, you won’t see anything due to alpha=0, i.e. full transparency.
    • You can look at the full, minimal code example, here.


    Of Rendering Mini Maps Inside Unity UI

    My use case was simple: I wanted to create level previews for my current puzzle game project Puzzle Pelago, and I wanted to try making a simple tiling system based on a custom UI mesh. The requirements I was eyeing was that it should behave like all the other UI elements in unity, i.e. it should fit inside its RectTransform, it should work inside a masked ScrollView, and it should respond to disabled state tinting since it would be living inside of a button.  

    What I ended up with looks something like this:



    The path there was not that bad, but still frustrating at times since all I found online was forum posts and Unity's own source code to go off of. So here I want to build a simplified example in which we will render a grid of textured quads inside a UI element, using one script. This should take all the hurdles for building any kind of (flat, 2d) UI geometry you might want to build. 


    Unity Scene Setup

    Alright, let’s set up the scene as follows: 

    1. Open the Unity project and Scene you want to work in. If there is no Canvas in the scene yet, create one! For this tutorial, I left all the properties at default.
    2. Inside the Canvas, create a ScrollView - we will want to check that our new UI component works inside of that!
    3. Inside the ScrollView > Viewport > Content, create new empty game object - let’s call it MyUiElement
    4. Add a CanvasRenderer component to the new game object, and then add new script: MyUiElement
    5. Open the new script in your favourite c# editor (I love Rider btw.), and go back to Unity’s scene.
    6. To make our lives easier, we will want to set the Scene View’s render mode to “Shaded Wireframe” so we can see our UI mesh geometry in detail. Also, it is useful to switch to the 2D view perspective, select our “MyUiElement” object and press F, so unity zooms in just right.




    Implementing the Custom Unity UI Mesh Script in C#

    Now we can go ahead and implement our new C# script!

    First off, our new script needs to at least derive from Graphic . But, if masking inside of ScrollViews, for example, needs to work, we better derive from MaskableGraphic. Otherwise, our graphics will render outside of the mask, too. Lol.

    Also, we want to be able to set the size of the grid cells in the editor, so we should add a public field for that.

    public class MyUiElement : MaskableGraphic
        public float GridCellSize = 40f;


    Next, we want to be able to use a texture for our UI elements. Looking at Unity’s own implementation, e.g. that of the Graphic (source code) base class or the default Image (source code) UI element, we can see that a common pattern is to …

    • … define Texture/Material slots as properties, such that when the texture is changed in the inspector, we can trigger Unity UI to re-render even while in edit mode. This is done by calling SetMaterialDirty() and SetVerticesDirty().
    • … implement mainTexture as a default overridden property such that if no texture is provided, we return the default white texture.
        Texture m_Texture;
        // make it such that unity will trigger our ui element to redraw whenever we change the texture in the inspector
        public Texture texture
                return m_Texture;
                if (m_Texture == value)
                m_Texture = value;
        public override Texture mainTexture
                return m_Texture == null ? s_WhiteTexture : m_Texture;


    Next, we have to override OnPopulateMesh() to do our rendering. It takes a useful little helper object for building meshes, the VertexHelper , as its argument. It tracks the vertex indices for you, and lets you add vertices, uvs and tris without having to do lots of array arithmetic and index tracking. It must be Clear()’ed before building a new mesh.

    I found it useful (and you may, too) to use a little quad-making helper function, AddQuad():

    // helper to easily create quads for our ui mesh. You could make any triangle-based geometry other than quads, too!
        void AddQuad(VertexHelper vh, Vector2 corner1, Vector2 corner2, Vector2 uvCorner1, Vector2 uvCorner2)
            var i = vh.currentVertCount;
            UIVertex vert = new UIVertex();
            vert.color = this.color;  // Do not forget to set this, otherwise 
            vert.position = corner1;
            vert.uv0 = uvCorner1;
            vert.position = new Vector2(corner2.x, corner1.y);
            vert.uv0 = new Vector2(uvCorner2.x, uvCorner1.y);
            vert.position = corner2;
            vert.uv0 = uvCorner2;
            vert.position = new Vector2(corner1.x, corner2.y);
            vert.uv0 = new Vector2(uvCorner1.x, uvCorner2.y);
        // actually update our mesh
        protected override void OnPopulateMesh(VertexHelper vh)
            // Let's make sure we don't enter infinite loops
            if (GridCellSize <= 0)
                GridCellSize = 1f;
                Debug.LogWarning("GridCellSize must be positive number. Setting to 1 to avoid problems.");            
            // Clear vertex helper to reset vertices, indices etc.
            // Bottom left corner of the full RectTransform of our UI element
            var bottomLeftCorner = new Vector2(0,0) - rectTransform.pivot;
            bottomLeftCorner.x *= rectTransform.rect.width;
            bottomLeftCorner.y *= rectTransform.rect.height;
            // Place as many square grid tiles as fit inside our UI RectTransform, at any given GridCellSize
            for (float x = 0; x < rectTransform.rect.width-GridCellSize; x += GridCellSize)
                for (float y = 0; y < rectTransform.rect.height-GridCellSize; y += GridCellSize)
                        bottomLeftCorner + x*Vector2.right + y*Vector2.up,
                        bottomLeftCorner + (x+GridCellSize)*Vector2.right + (y+GridCellSize)*Vector2.up,
                        Vector2.zero, Vector2.one); // UVs
            Debug.Log("Mesh was redrawn!");


    Note that in the AddQuad() function, we set position, uv, and color! Since in the UI material, texture is multiplied with the color by default. Leaving this at default, i.e. (r=0,g=0,b=0,a=0), this will yield 100% transparent material. So all you see is nothing, and if you are wondering why, this might be it. Here we use the component’s inherited color slot.

    Since we want our grid to update whenever the RectTransform is resized, we should also override OnRectTransformDimensionsChange():

        protected override void OnRectTransformDimensionsChange()


    This should do. Now, back to our Unity scene, we should see a grid of white squares inside our RectTransform. To change this, we can select one of unity’s default textures in our texture slot.



    Adjusting the size of the RectTransform or the value of our Grid Cell Size, we can see that the grid updates automatically. Going into play mode, we should also be able to drag around the scroll view’s contents and have the grid be masked correctly. 

    Screenshot5.png Screenshot6.png




    You can have a look at the full code example, here

    Of course, we are not limited to rendering quads, either, since the basic geometry we created here consist of triangles. So any 2D mesh should be possible to draw, and in principle, it could be animated, too! 

    Anyway, if anything in my writeup is unclear, don’t hesitate to ask questions in the comments or via Twitter, @hallgrimgames. 

    Good luck with your project!


    Note: This article was originally published on the Hallgrim Games blog, and is republished here with the kind permission of the author Christopher.

      Report Article

    User Feedback

    There are no comments to display.

    Create an account or sign in to comment

    You need to be a member in order to leave a comment

    Create an account

    Sign up for a new account in our community. It's easy!

    Register a new account

    Sign in

    Already have an account? Sign in here.

    Sign In Now

  • Advertisement
  • Advertisement
  • GameDev.net and Intel Contest

    GameDev.net and Intel® have partnered up to bring GameDev.net members a gamedev contest running until December 21, 2018 - Submit your game for Intel® Certification and you could win big!

    Click here to learn more and submit your game.

  • Latest Featured Articles

  • Featured Blogs

  • Advertisement
  • Popular Now

  • Similar Content

    • By GameDev.net
      GameDaily.Biz spoke to Improbable about its new shortcuts to multiplayer game development for Unity and Unreal. 

      Improbable helps game developers build believable online worlds with its bespoke technology, SpatialOS. Now, that task is much easier and accessible for those building games on the technology with the recent release of the SpatialOS Game Development Kit (GDK) for Unity. With these kits, Improbable hopes that developers find it easier to create vast, dynamic and unique worlds.
      This GDK for Unity includes a 200-gamer, first-person project that allows developers to experiment and tinker with their ideas for what their vision of a multiplayer game will look like.
      GameDaily.Biz met with Improbable’s Head of Product Marketing, Paul Thomas, and Head of Comms, Daniel Nye Griffiths, to speak about the SpatialOS GDK for Unity, as well as the upcoming launch of the SpatialOS GDK for Unreal Engine.
      In its first week, the SpatialOS GDK for Unity achieved over 2,000 developer sign ups to use it. “What we're trying to do is basically make it really fast for people to build multiplayer games,” said Thomas. “It comes with all the multiplayer networking so that developers don’t have to do any multiplayer networking. It comes with feature modules to allow [easy] solutions to common multiplayer problems, like player movement and shooting. And it comes with a cool starter project where you have 200 players in a free-for-all scenario. You can obviously use the power of SpatialOS to scale that project up to more players, with NPCs, and things like that. It gives people a really good base to start building multiplayer games.”
      There are several games currently in development or early access that utilize SpatialOS. The first into Early Access was Spilt Milk Studios’ Lazarus, a space MMO where the player becomes a pilot in a universe that ends every week, complete with a map that’s twice the size of Austria. Additionally, Bossa Studios released its survival exploration game Worlds Adrift into Steam Early Access earlier this year.
      Also using SpatialOS is Scavengers from Midwinter Entertainment, a studio founded by former 343 Industries studio head and Halo 4 Creative Director, Josh Holmes; the game is heavily inspired by his Halo 5: Guardians’ multiplayer mode, Warzone. Right alongside that company, Berlin-based Klang Studios is working on Seed, a simulation MMO that, according to its developers, lets players “interact and collaborate to create a world driven by real emotion and aspiration.”
      According to Thomas, for those looking to use the SpatialOS GDK for Unity, there is no limit to  what their games can do with Improbable’s tech.
      “What we're doing is expanding the possible gameplay you can do. Traditionally, when you make a multiplayer game, you're constrained by one single server. So you can say you have a 64-player game with a handful of NPCs or you could have a world that's 3km by 3km. With Spatial, you can go beyond that, test a much broader canvas to start thinking about different gameplay.”
      “You can go for a massive online persistent MMO with 10,000 players and hundreds of thousands of NPCs, something very, very vast and big like that. But you can also have smaller experiences. For example, there's a lot of interesting space in just extending what you see in the Battle Royale genre and session-based gameplay.”
      Thomas continued: “Our partners at Automaton have a game in development called Mavericks. The interesting thing there is they have a Battle Royale with 1,000 people, but what I really find interesting is the gameplay mechanics they've put in, like footprints so you can track people. They've added a cool fire propagation mechanic so you can start a fire that  spreads across the map and changes the world. Or you can add destructible buildings and things like that.”
      “So I think even looking at smaller scale games, we add a lot of value in terms of the new gameplay you can start adding. I'm just interested to see what people do with this extra power - what they can come up with.”
      While Battle Royale games and MMOs are obvious standouts for genres that best fit with SpatialOS, Thomas introduced some other ideas of genres that could benefit from the technology.
      “I also think there's a space for very interesting MMORTSs as well,” he said. “An RTS where you have persistent systems, like telling AIs to do things and then coming back to them a week later and seeing what's happened is an interesting space.”
      “I also see interesting mobile experiences that could come up. Having these worlds where you lay down some interesting things and then come back a few weeks later to see how they've evolved and changed, and the massive player interaction. Say for example with Pokemon Go, we can actually roam around the world and battle on the streets. I can see something like that working very well. Again, these are just ideas we've had and talked to people about. It's about giving people that flexibility and the ability to explore these ideas.”
      Klang’s Seed
      Griffiths added the possibility of events in a game that will have a massive, rippling, and lasting impact on its world as something that has people excited. One example he gives is how someone on one side of the map can do something that’ll have a knock-on effect for the rest of the world in real time.
      “There's a whole bunch of different angles you can take, some of which are about much larger player numbers or a much larger map, but there are other things you can do which are taking a relatively constrained game experience, a smaller map, a smaller number of players and adding richness to the game as well.”
      In fact, this is something that Thomas refers to as a “persistent in memory database,” meaning that for every object in the game world, there’s a history. Two examples cited by Thomas: “...a player could chop down a tree and that tree stays disappeared forever. Or a player can kill a big monster that was raiding a town and that town no longer gets raided by that monster, and this changes the dynamics of the world. Worlds can have a history. That means players can have a lot more meaning in these MMO worlds.”
      “Normally in MMOs, they're kinda like roller coaster rides: you go into a dungeon, you kill the boss and that guy respawns. It all resets,” Thomas continues. “But in Spatial MMOs, you could have these persistent effects that should change the gameplay meaningfully for all the rest of the player base.”
      “The other one I think that is interesting is the level of dynamism that you could have. So because you can have so much more server-side compute, you could potentially have NPCs roaming around the world changing their mind and deciding all of a sudden, 'oh, we're going to attack this player's base' or 'we're gonna go attack this town' and they have a lot more range and emotion and intelligence to them that you'd not see in other MMOs.
      “Normally in MMOs, NPCs sit there tethered. You go near them and they come and attack you, you run away, and they go back to where they were. In a Spatial MMO, that NPC can trace you across the whole map or a group of them can decide to get together and attack someone..”

      Bossa Studios' Worlds Adrift

      Next week, Improbable plans to launch its SpatialOS GDK for Unreal Engine, which will have a big focus on ease of use for access to Unreal, as well as a big emphasis on porting your projects to SpatialOS.
      “One of the things we'll be trying to push is a porting guide so you'll be able to take your existing Unreal game, move it onto SpatialOS and then you can grow to expand it with new and extra gameplay,” says Thomas. “ You can bring across your existing Unreal game and it feels very, very native and similar to Unreal if you're familiar with Unreal.”
      Griffiths continued, explaining how testing these experiences includes free cloud deployments, to a certain point. “If you're developing in SpatialOS in other ways, we provide a sandbox environment so you can get your game running. When you’re happy, you can port it over and sort of experiment with it in a free sandbox environment with a small number of cores to get started.”
      Based on what we learned, Improbable’s SpatialOS GDK for Unity will give developers enhanced flexibility to produce more in depth and engaging videos games. That said, we look forward to catching up with the company in the near future to see how this exciting technology is being used in the different games that we play.
    • By MiniDarkOF
      Hello Again,
      I'm trying to create a "sound expansion"

      The Example:
      a nuclear explosion sound has 1000ft of audible sound area
      players who is next to the explosion hear it first
      players who is far to the explosion will hear after some seconds
      when the sound reaches its area limit, it ends with a "fade-out"

      The Point:
      i already know how to create fade-out sound effect in Unity
      know i want to know how i can create this "sound expansion" effect
    • By Florian Gionnane
      Hi everybody !
      We are an indie startup called Darkstar Games !
      We are just creating our first game called Greater powers, a novel type medieval fantasy TCG MMORPG with which we use unity. 
      We develop our games for Android, PC, iOS, and we have a software kit developer contract with Microsoft to adapt them to VR Microsoft HoloLens and VR Magic Leap in the future.
      We are developing our own alpha for the Kickstarter campaign at the moment !
      So we are actively searching for motivated programmers willing to take place in our project to build the engine we are creating of our own right now ! The game is coded in C# and any unity experience is greatly appreciated! 
      We collaborate to the startup worldwide remotely !
      Programmers collaborating to the project such as building the alpha become shareholders and are hired in the start-up launch !
      Here are some links about the project:
      If anyone interested, please send your resume to flosambora123@gmail.com
      Have a nice day !

    • By Glasshalfpool
      Hi there
      I'm working on a simple racing game at the moment that I like to pitch as Thumper vs. Burnout vs. Journey.
      In a nutshell it's a single player experience where the player races across a city in the dead of night with a time limit of one hour. The main mechanic being that driving well earns the ability to go faster, making things more challenging and opening up shortcuts and alternative routes, while mistakes (colliding with walls for example) make the player loses their highest speed and have to re-earn it.
      I have a grand vision for an a pounding, dynamic sound track with elements being added to the music as the player goes faster and I'm looking for someone to collaborate with on the audio effects.
      Here is a video of the early direction and feel of the project (it's moved on since, but this still gives a sense of the style):  
      Contact me if you're interested in the opportunity to work on an interesting unique soundscape with me.
      Kind regards,

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

GameDev.net is your game development community. Create an account for your GameDev Portfolio and participate in the largest developer community in the games industry.

Sign me up!