Live 3D headshots and 2D portraits for party frames, HUDs and dialogue.
Portrait Avatars is a Unity asset by Magic Pig Games that adds character portraits to your game's UI: live 3D renders of your characters or 2D sprites, for party frames, avatar headshots and talking heads. After setup, each portrait takes one line of code.
Version 1.2.1 · updated June 18, 2026 · Unity 6.0 or newer
Each 3D portrait is your character rendered by its own camera into its own RenderTexture and shown in the UI. Animation and lighting changes show up in the portrait as they happen.
A 2D portrait is a sprite in a UI Image, with no camera, RenderTexture or layer. Mix both kinds, for example 3D for the party and 2D for everyone else.
Call PortraitAvatars.instance.Create3DPortrait() or Create2DPortrait() and a framed portrait appears in the panel. You get back a handle to set its sprite or remove it later.
All 3D rigs spawn at the same spot, but each gets its own layer, so its camera renders only that character and its lights touch nothing else. The number of layers you dedicate sets how many 3D portraits can be live at once.
Put the manager under your player and 3D portraits spawn where the player stands, so scene lights reach them as the player moves. Each portrait can also carry its own lights.
Change the frame, image and background colors and the portrait lights' color and intensity, for all portraits or just one, with a smooth transition or instantly. New portraits start with the last values you set.
Portrait cameras can refresh every frame or at a set rate, such as 15 times per second. Portraits can also share one background camera, often showing the world behind the player, with its own refresh rate.
Restyle the included UI Portrait prefab, which comes with a border, background and a simple health bar. Subclass PortraitAvatars, Portrait3D, AvatarCamera or PortraitUI to add your own logic.
Portrait Avatars comes with skills for AI coding assistants such as Claude Code and Codex. Once they're installed, your assistant knows how Portrait Avatarsworks, so you can ask for what you want in plain English:
Two scene components run the system. The PortraitAvatars manager creates and destroys portraits and remembers your color and light settings. The PortraitsPanel sits under a Canvas and adds a UI Portrait cell to its grid for each new portrait.
A 3D portrait starts as a prefab: a Portrait3D component on the root, an Avatar Camera child with a Camera and an AvatarCamera component, optional lights, and your character. The package includes a template prefab you can duplicate. When you call PortraitAvatars.instance.Create3DPortrait(), the manager spawns that prefab as its own child, then:
RenderTexture, shown in the cell’s RawImage.Every 3D rig spawns at the same local position, and the layers keep them apart: each camera sees only its own character. So you create one Unity layer per 3D portrait you want on screen at once (for example Portrait0, Portrait1 and Portrait2) and select them in the manager’s Available Layers. Three layers means up to three live 3D portraits.
A 2D portrait skips the camera, texture and layer. Create2DPortrait() adds a cell that shows a sprite in a UI Image, and SetSprite() on the returned handle sets the art.
Each 3D portrait runs its own camera, and too many cameras slow your game down. Depending on the project and platform, 4, 6 or even 8 at once may be fine, so check your frame rate as you add them. Use 3D for characters that should move and react to light, like the player’s party or a talking NPC, and 2D for everyone else.
Version 1.2.1 added two ways to lower that cost. Portrait cameras can refresh at a set frames per second instead of every frame. And when all portraits share the same background, such as the game world behind the player, one background camera renders it at its own rate, so the portraits themselves can update more slowly.
In a first-person game you usually put the manager under your player. 3D portraits then spawn where the player stands and pick up the world’s lighting as they move. The docs explain the tradeoffs, like light bleeding through walls, and fixes such as scaling the avatar down and tightening its camera’s clipping planes.
The runtime code lives in the MagicPigGames.Portraits namespace, in its own assembly definitions. Each create call returns an InGamePortrait handle. The color and light methods (SetUIColor, SetImageColor, SetBackgroundColor, SetLightColor, SetLightIntensity) change every portrait or one by index. To remove portraits, call DestroyPortrait() or DestroyAllPortraits(): they release the RenderTexture and free the layer for the next one.
For your own logic, subclass PortraitAvatars, Portrait3D, AvatarCamera or PortraitUI, or add a loader component that dresses each avatar after it spawns, like the demo’s DemoAvatarLoader. The scripting documentation covers the full API.
Add the PortraitAvatars manager to your scene and the PortraitsPanel under a Canvas, then assign a 3D portrait prefab and your portrait layers. Call PortraitAvatars.instance.Create3DPortrait() and the portrait appears as a new cell in the panel.
One for each Unity layer you select in the manager's Available Layers, since every 3D portrait needs its own layer. Each one also runs a camera, so watch your frame rate; depending on the project and platform, 4, 6 or even 8 at once may be fine. 2D portraits need no layer or camera.
It works the same in any render pipeline. On Unity 6.0 the demo scene uses the Built-in Render Pipeline, and on Unity 6.3 it uses URP.
Call DestroyPortrait() with the portrait's handle or index, or DestroyAllPortraits() to clear them all. These remove the avatar and its UI cell, release the RenderTexture and free the layer, which destroying the GameObject yourself does not do.
Yes. With the manager under your player, 3D portraits spawn at the player's position, so scene lights affect them as the player moves. Portrait Avatars also works with our Runtime Color Sampler asset to adjust UI colors from in-world lighting, and a bonus demo scene shows the two together.
Yes. The package includes an AI skill for Claude Code and Codex that knows the setup and the runtime API. With it, your assistant can build portrait prefabs from your characters, add the manager and panel to your scene and write the code, working in the editor through the Unity MCP bridge when it is running.