Material AI Studio User Guide

Material AI Studio User Guide

Material AI Studio lets you create, inspect, improve, and validate Unreal Engine materials by describing what you want in a chat window inside the editor.

This guide only covers functions currently visible in the Material AI Studio interface.

Requirements

• Unreal Engine 5.6
• Windows 64-bit
• Material AI Studio enabled in the project
• Access to DeepSeek, OpenAI, or another OpenAI-compatible API service

Install and Enable

1. Close Unreal Editor.
2. Copy the MaterialAIStudio folder into the project's Plugins folder.
3. Open the Unreal Engine project.
4. Open Edit > Plugins.
5. Search for Material AI Studio.
6. Enable the plugin if it is not already enabled.
7. Restart Unreal Editor when requested.

Open the Window

Use either method:

1. Open Window > Material AI Studio.
2. Or click Material AI on the editor toolbar.

The window contains:

1. More menu
2. Provider selector: DeepSeek, OpenAI, and API (other OpenAI-compatible services).
3. Optional model field
4. Colored provider status and status text
5. Setup Guide when an API key is missing
6. Audit Selected
7. Improve Copy
8. Selected material name
9. Conversation area
10. Prompt input and Send

First-Time Provider Setup

Only one provider needs to be ready. Select the provider you want from the top of the window.

The status indicator shows its condition:

• Green: ready
• Amber: checking
• Red: setup is required

Hover over the status to see more information.

Recommended One-Time Step: Build the Function Catalog

After enabling the plugin, run this once in the editor console (open it with the backtick key `):

MaterialAI.BuildFunctionCatalog

This indexes every material function in the engine and the project (a progress bar appears; it takes one to three minutes). Afterwards the assistant knows the exact input and output pins of every material function, which noticeably improves complex materials such as parallax walls and layered surfaces. Without it the plugin still works, with slightly less reliable function wiring. Re-run it after adding many new material functions to the project.

Set Up DeepSeek

1. Select DeepSeek.
2. If it is not ready, click Setup Guide.
3. Create a DeepSeek API key as instructed.
4. Open Editor Preferences > Plugins > Material AI Studio.
5. Find the DeepSeek section.
6. Paste the key into DeepSeek API Key.
7. Return to Material AI Studio.
8. Confirm that the status turns green.

DeepSeek is API-key based and runs over native HTTP.

Set Up OpenAI

1. Select OpenAI.
2. If it is not ready, click Open Settings (or Setup Guide).
3. Create an API key in your OpenAI API dashboard.
4. Open Editor Preferences > Plugins > Material AI Studio.
5. Find the OpenAI section.
6. Paste the key into OpenAI API Key (or set the OPENAI_API_KEY environment variable).
7. Optionally change OpenAI Model (default gpt-4.1).
8. Return to Material AI Studio and confirm that the status turns green.

OpenAI runs natively over HTTP with an API key. For other OpenAI-compatible services (Moonshot/Kimi, Qwen, OpenRouter, a local Ollama, or any custom endpoint), use the API provider and its OpenAI-Compatible API settings section instead.

Select a Provider and Model

Before sending a request:

1. Select DeepSeek, OpenAI, or API.
2. Check that the provider status is green.
3. Review the model field beside the provider selector.
4. Keep the displayed default unless you specifically need another model.
5. To override it, enter the exact model name supported by your provider.

Changing the provider updates the model field and the connection status.

Create a Material

Basic Procedure

1. Open Material AI Studio.
2. Select a ready provider.
3. Click the prompt box at the bottom.
4. Describe the material you want.
5. Include the intended asset name and /Game/... destination folder.
6. Include the controls you want exposed to artists.
7. Ask for validation at the end.
8. Click Send or press Ctrl+Enter.
9. Watch the activity strip and progress steps.
10. Wait for the final response.
11. Click the generated asset button in the response to open it and select it in the Content Browser.
12. Review the material and its parameter values.
13. Save the project.

Example:

Create a polished red car paint material named M_CarPaint under /Game/Materials/CarPaint. Add adjustable base color, roughness, metallic, clear-coat strength, flake intensity, and flake scale. Create a useful default instance and validate the result.

Information to Include

For more reliable results, state:

• What the material represents
• The desired visual style
• The asset name
• The destination folder
• Required adjustable parameters
• Whether an instance should also be created
• Whether the result should be optimized
• Whether the result should be validated

Example:

Create a reusable wet stone material for environment props. Save it as M_WetStone under /Game/Materials/Stone. Add stone color, roughness, normal strength, texture tiling, wetness, puddle amount, and edge darkening controls. Create dry and rainy instances, then validate the result.

Continue Refining a Result

Keep using the same conversation when adjusting a generated result.

1. Wait for the current request to finish.
2. Review the generated material.
3. Return to the prompt box.
4. Refer to the exact material or instance name.
5. Describe only the changes you want.
6. State which parts must remain unchanged.
7. Click Send.
8. Open the asset again from the response and review the changes.

Example:

Keep M_CarPaint and its current parameters. Make the red darker, reduce the flake intensity, increase clear-coat roughness slightly, and validate it again.

Use a Starter Prompt

When the conversation is new, the window may show Try a starter suggestions.

1. Review the displayed suggestions.
2. Click a suggestion that is close to your goal.
3. The text is placed in the prompt box.
4. Edit names, destination paths, colors, or other requirements.
5. Click Send or press Ctrl+Enter.

Starter prompts are templates. Review and customize them before sending.

Four starters are drawn at random for each new conversation (clearing the conversation draws a new set). When DeepSeek is configured, the pool quietly grows in the background with fresh ideas over time.

Audit Selected

Audit Selected checks a master material selected in the Content Browser. It does not require an AI request.

Run an Audit

1. Open the Content Browser.
2. Select one master material asset.
3. Return to Material AI Studio.
4. Confirm that Selected: <material name> appears beside the action buttons.
5. Click Audit Selected.
6. Wait for the material to compile.
7. Read the audit report added to the conversation.

The report can show:

• Grade and score
• Pixel and vertex instruction counts
• Sampler and texture sample counts
• Errors
• Warnings
• Suggestions

If the button is disabled, confirm that a master material is selected and that another task is not currently running.

Improve Copy

Improve Copy asks the selected provider to improve a duplicate of the selected master material.

Create an Improved Copy

1. Make sure the chosen AI provider is ready.
2. Open the Content Browser.
3. Select one master material.
4. Return to Material AI Studio.
5. Confirm that the correct material name is displayed.
6. Save the project before continuing.
7. Click Improve Copy.
8. Watch the activity strip and progress steps.
9. Wait for the final response.
10. Click the new asset button in the response.
11. Compare the new material with the original.
12. Review the new parameters and visual result.
13. Save the improved asset if you want to keep it.

The new asset normally uses an _AI_Improved suffix. If that name already exists, a numbered suffix may be used. The original selected material is not edited by this button.

Monitor a Running Request

While a request is active:

1. The activity strip shows the current action.
2. Individual progress steps appear in the assistant message.
3. A spinner marks the currently running step.
4. Completed steps receive a success mark.
5. Failed steps receive a failure mark.
6. After completion, the steps collapse into a summary.
7. Expand the summary to inspect individual steps.

Some complex material requests can take several minutes.

Stop a Request

1. Click Stop in the activity strip.
2. Wait for the status to report that the request stopped.
3. Read the latest conversation message.
4. Check the Content Browser for any assets created before cancellation.
5. Review those assets before deleting, keeping, or continuing the work.

Stopping a request does not automatically remove work completed before cancellation.

Use Conversation Controls

Copy a Message

1. Find the message.
2. Click Copy in its top-right corner.
3. The full message text is copied to the clipboard.

Edit and Resend a Prompt

User messages show a resend button.

1. Find your earlier prompt.
2. Click its resend button.
3. The prompt is placed back into the input box.
4. Edit it.
5. Click Send.

Open a Generated Asset

1. Find an asset button below an assistant response.
2. Click it.
3. Unreal Editor selects the asset in the Content Browser.
4. The asset editor opens.

Return to the Latest Message

1. Scroll upward to review earlier messages.
2. When Latest appears, click it.
3. The conversation returns to the newest message.

Copy the Entire Conversation

1. Click More.
2. Select Copy Conversation.
3. The full conversation is copied to the clipboard.

Clear the Conversation

1. Wait for any running request to finish, or stop it.
2. Click More.
3. Select Clear Conversation.
4. The visible conversation is cleared.
5. Start a new request in the prompt box.

Clearing the conversation does not delete materials already created in the project.

More Menu

The visible More menu contains:

• Copy Conversation: copy all visible messages
• Clear Conversation: clear the current chat
• Write MCP Client Configs: optional advanced configuration; not required for normal in-editor use
• Show Knowledge Topics: display the material topics currently available to the assistant

Show Knowledge Topics

1. Click More.
2. Select Show Knowledge Topics.
3. Read the topic list added to the conversation.
4. Use a relevant topic name or effect description in your next prompt if useful.

Teach the Assistant Project Knowledge (Optional)

The assistant reads a knowledge base of material guides and effect recipes before building. You can extend it without restarting the editor:

Add Your Own Notes

1. Create a .md text file. The file name becomes the topic name (for example our_team_naming_rules.md).
2. Write your conventions, parameter naming rules, or effect notes in plain English.
3. Save the file into <YourProject>/Saved/MaterialAIStudio/Guides/.
4. The knowledge is live immediately — confirm with More > Show Knowledge Topics.

A file with the same name as a built-in topic replaces that topic.

Learn From an Existing Master Material

If the project already contains a well-made master material, the assistant can study it (requires a DeepSeek key):

1. Open the editor console (backtick key).
2. Run: MaterialAI.LearnMaterial M_YourMasterMaterial
3. Wait a few minutes; the result is written to the project knowledge folder as example_<name>.
4. From then on, requests like "build a material following our master material conventions" use what it learned.

Distill Knowledge From Files

MaterialAI.DistillGuide <topic> <file path> converts a source file, shader file, or notes document into a knowledge guide using DeepSeek. Intended for advanced users.

Prompt Writing Guide

A practical prompt follows this order:

1. Material purpose
2. Visual appearance
3. Asset name and destination
4. Adjustable parameters
5. Requested instance variants
6. Optimization or validation requirement

Template:

Create a [material type] for [purpose]. It should look [visual description]. Save it as [asset name] under [/Game/path]. Add adjustable [parameter list]. Create [instance variants if needed]. Optimize and validate the result.

Example: Lava

Create an animated lava material named M_Lava under /Game/Materials/Lava. Use dark crust, glowing cracks, adjustable flow speed, distortion, emissive intensity, and edge glow. Create one default instance and validate it.

Example: Snowy Rock

Create a snow-covered rock material named M_SnowRock under /Game/Materials/Snow. Add upward-facing snow accumulation, snow amount, sparkle intensity, rock roughness, normal strength, and tiling controls. Create light-snow and heavy-snow instances, then validate it.

Example: Glass

Create an architectural glass material named M_WindowGlass under /Game/Materials/Glass. Add tint, opacity, roughness, refraction, normal distortion, and edge highlight controls. Keep it suitable for large windows and validate it.

Troubleshooting

Provider Status Is Red

1. Select the intended provider.
2. Click Setup Guide if visible.
3. Follow the API key instructions shown in the conversation.
4. Confirm that the status turns green.

Send Is Disabled

Confirm that:

1. The selected provider is ready.
2. The prompt box contains text.
3. No other request is running.

Audit Selected Is Disabled

Confirm that:

1. A master material is selected in the Content Browser.
2. The selected asset name appears in Material AI Studio.
3. No other task is running.

Improve Copy Is Disabled

Confirm that:

1. A master material is selected.
2. The selected provider is ready.
3. No other request is running.

Generated Asset Is Hard to Find

1. Find the final assistant response.
2. Look for an asset button under the response.
3. Click it to open and select the asset.
4. If no asset button appears, read the response for the reported path or error.

Result Needs Changes

1. Keep the same conversation.
2. Name the material you want to adjust.
3. Describe the exact visual or parameter changes.
4. State what should remain unchanged.
5. Ask for validation again.

Recommended Workflow

1. Save the project.
2. Open Material AI Studio.
3. Select a provider and confirm the green status.
4. Enter a clear request with an asset name and destination.
5. Send it and monitor progress.
6. Open the generated asset from the response.
7. Review its appearance and parameters.
8. Continue refining it in the same conversation.
9. Select the finished master material.
10. Run Audit Selected.
11. Save the project and submit the assets to source control.