vale

VALE Setup Guide

This is the “I just cloned the repo, now what” guide. Follow it top to bottom and you will have a playable prototype of VALE running in the Unity editor in about 30 to 50 minutes, depending on how fast your downloads go.

If you get stuck, the Troubleshooting section at the end covers the most common issues. For a high-level overview of what you are building, see README.md. For details on the codebase after setup, see ARCHITECTURE.md.

Prerequisites

You will need the following installed before opening the project.

Unity Hub

  1. Go to https://unity.com/download and download Unity Hub for your operating system (Windows, macOS, or Linux).
  2. Run the installer and sign in with a Unity ID. If you do not have one, create a free account at https://id.unity.com.

Unity 6 editor

  1. In Unity Hub, click Installs (left sidebar) then + (top right).
  2. Select Unity 6 (version 6000.0.x). Any LTS release works. The project targets 6000.0.23f1, but any 6000.0.x will import without issues.
  3. In the Modules step, make sure High Definition RP is checked. Also check Cinemachine, Input System, and VFX Graph if they appear (they are usually included automatically by HDRP).
  4. Click Install. This can take 10 to 20 minutes.

Minimum hardware

No other software required

You do not need to install Visual Studio, Rider, or any C# IDE. The Unity editor has a built-in script viewer, and you will only be filling in inspector fields in this guide, not writing code.

Open the project

  1. In Unity Hub, click Open (left sidebar).
  2. Browse to the folder where you cloned the repo and select the apps/vale/ directory. It should show a Unity icon and a label like “VALE (6000.0.x)”.
  3. Click Open.

The first open triggers a full package import (HDRP, Cinemachine, Input System, VFX Graph, ProBuilder, Terrain Tools). You will see a progress bar in the bottom-left corner of the Unity window. On a modern SSD this takes about 3 to 5 minutes. On a slower drive, give it up to 10.

While you wait, the console will show lines like:

Importing package 'com.unity.render-pipelines.high-definition'...
Importing package 'com.unity.cinemachine'...

Do not close the editor. If the console shows red errors after the import finishes, see Troubleshooting before continuing.

Once the import finishes, the editor will show an empty or partially built scene. This is expected. The scene is generated by the editor menu items in Step 7 below.

Configure Input

The game uses the Unity New Input System. You need to create a single .inputactions asset that defines all player and UI actions.

Create the input asset

  1. In the Project window (bottom-left), navigate to Assets/Vale/Settings/. If the Settings folder does not exist, create it: right-click in Assets/Vale/, then Create > Folder, name it Settings.
  2. Right-click in the Settings folder.
  3. Click Create > Input Actions.
  4. Name the new asset ValeInput (Unity appends .inputactions automatically). It should appear as Assets/Vale/Settings/ValeInput.inputactions.
  5. Click the new asset to select it. The Inspector panel (bottom-right) will show the Input Action Asset fields.

Add the “Player” action map

The new asset comes with an empty Player action map already. Select the Player action map in the Inspector. You will see an Actions section with a (+) button. For each action below, click (+), then fill in the fields.

Action name Interaction type Control(s) to add
Move Value (Vector 2) W (Y axis, +1), S (Y axis, -1), A (X axis, -1), D (X axis, +1)
Look Value (Vector 2) Mouse X (X axis), Mouse Y (Y axis)
Jump Button Space
Interact Button E
ToggleFlight Button F
Sprint Button Left Shift
QuestLog Button Tab
Pause Button Escape

How to add a key (example for Move):

  1. Click (+) next to Actions.
  2. Set Name to Move.
  3. Set Type to Value.
  4. Set Expected Control Type to Vector 2.
  5. Click (+) in the Interactions or Bindings section to add a binding. In the binding row, click the Control field, type W, and confirm. Then set the Processor or Axis to Y = +1.
  6. Repeat for S (Y = -1), A (X = -1), D (X = +1).

For Look, the controls are Mouse X and Mouse Y (these are built-in mouse delta controls available in the control picker).

For the button actions (Jump, Interact, etc.), set Type to Button and add the corresponding key as the binding.

Add the “UI” action map

  1. At the top of the Inspector, click (+) next to Action Maps.
  2. Name it UI.
  3. Select the UI action map.
  4. Add two actions:
Action name Interaction type Control(s)
Submit Button Enter, Space
Cancel Button Escape

Save

Click File > Save (or press Ctrl+S). The asset now exists on disk at Assets/Vale/Settings/ValeInput.inputactions.

You will drag this asset onto the InputManager component later (Step 9).

Set up HDRP

HDRP (High Definition Render Pipeline) is already listed in the project’s Packages/manifest.json. Unity imported it when you opened the project. You just need to make sure it is set as the active render pipeline.

Verify the current setting

  1. Go to Edit > Project Settings > Graphics.
  2. In the Scriptable Render Pipeline Settings field at the top of the window, check whether an asset is already assigned.

If you see an HDRP asset (its name usually contains “HDRP” or “HDRenderPipelineAsset”), you are done with this step.

If the field is empty

  1. Go to Window > Package Manager.
  2. In the Package Manager window, click the Packages: Installed tab (top-left dropdown).
  3. Find High Definition RP in the list and click it.
  4. In the detail pane, look for a Samples section and click Import HDRP Default Volume Profile. Follow the prompts.
  5. After the import, navigate to Assets/HighDefinitionRP/Settings/ in the Project window. You will find an asset called HDRenderPipelineAsset (or similar).
  6. Go back to Edit > Project Settings > Graphics and drag that asset into the Scriptable Render Pipeline Settings field.
  7. Also drag the same asset into the Scriptable Render Pipeline field in Edit > Project Settings > Quality if that field is empty.

Set the default Volume Profile

HDRP uses a “Volume Profile” to store post-processing effects (bloom, color grading, fog, etc.). The HDRP Starter Assets pack you import in Step 5 includes a ready-made profile. If you skip that pack, create a default one:

  1. Right-click in Assets/Vale/Settings/ > Create > HDRP > Volume Profile.
  2. Name it ValeVolumeProfile.
  3. Go to Edit > Project Settings > Graphics.
  4. In the HDRP tab (or the section labelled “High Definition RP”), set Default Volume Profile to ValeVolumeProfile.

Import free assets

VALE is designed to work with free, publicly available assets. The full list with URLs, licenses, and install instructions is in ASSETS.md. The three required assets are summarized here.

1. HDRP Starter Assets (Unity Asset Store, free)

This pack provides sample scenes, materials, and a volume profile tuned for HDRP. You will reuse its materials and lighting setup.

  1. In Unity, go to Window > Package Manager > Unity Asset Store (if Unity 6 shows it under Window > General > Asset Store, use that path).
  2. In the search box, type HDRP Starter Assets (or High Definition RP Starter Assets).
  3. Find the free pack (published by Unity Technologies) and click Get.
  4. After downloading, click Import and accept the default import settings.
  5. The pack will create a folder at Assets/HDRP Starter Assets/. Leave it where it is. The editor scripts in VALE reference materials from this folder.

2. Poly Haven HDRI (free)

The HDRI (high dynamic range image) provides the skybox and ambient light for the forest. Without it, the scene will look flat and dark.

  1. Open a browser and go to https://polyhaven.com/hdris.
  2. Search for kloofendal_48d (a partly cloudy South African landscape that suits a soft, golden forest light). Any bright, outdoor HDRI will work.
  3. Click the 4K resolution and download the .hdr file.
  4. In Unity, create the folder Assets/Vale/Settings/HDRIs/ if it does not exist (right-click Assets/Vale/Settings/ > Create > Folder).
  5. Drag the downloaded .hdr file from your file explorer into Assets/Vale/Settings/HDRIs/ in the Unity Project window.
  6. Select the imported .hdr file. In the Inspector, set Texture Type to Environment (360) and click Apply.
  7. Go to Edit > Project Settings > Lighting. In the Environment Lighting section, click the folder icon next to Source and set it to Use Custom. Then drag the HDR file into the Background field (or use Lighting > Environment > Skybox Material if you prefer the Material-based approach).

3. Kenney Nature Kit (free, CC0)

This pack provides low-poly trees, mushrooms, rocks, and other foliage prefabs. The forest populator script uses these to scatter vegetation.

  1. Open a browser and go to https://kenney.nl/assets/nature-kit.
  2. Click Download and extract the ZIP file.
  3. In Unity, create the folder Assets/Vale/Prefabs/Vegetation/ if it does not exist.
  4. Drag the Prefabs folder from the extracted Kenney package into Assets/Vale/Prefabs/Vegetation/.
  5. You should see prefabs for trees, mushrooms, grass patches, and rocks. The ForestPopulator editor script (Step 7) references prefabs from this folder by name.

Optional packs

For a richer look, you can also import:

These are optional. The prototype is playable without them.

Create data assets

The game systems (quests, dialogue, NPCs, collectibles) are driven by ScriptableObject data assets. You need to create one asset of each type per entry in the table below. All assets go in Assets/Vale/Data/.

Note: The Create > Vale > ... menu items appear in the context menu only after Unity has compiled the C# scripts. If you do not see them, wait for the compile to finish (watch the progress bar at the bottom of the editor) or restart the editor.

Prepare the Data folder

  1. In the Project window, right-click Assets/Vale/ > Create > Folder.
  2. Name it Data.

Quest data (2 assets)

Quest_MainQuest:

  1. Right-click in Assets/Vale/Data/ > Create > Vale > Quest Data.
  2. Name the file Quest_MainQuest.

  3. Select it and fill in the Inspector fields:

    Field Value
    questId main_quest
    title The Fading Light
    description The light of the Vale is fading. The Elder asks you to recover five lost Lumenshards and bring them to the Sacred Glade.
    offerText Will you help us, traveller? The five Lumenshards have been scattered across the Vale. Find them, speak to their keepers, and bring them to the Sacred Glade.

  4. In the Objectives list, click the Size field and set it to 6. Fill in each row:

    Index objectiveId description type targetId requiredCount
    0 talk_elder Speak with the Fairy Elder Talk fairy_elder 1
    1 collect_shard_1 Find the first Lumenshard Collect lumenshard_1 1
    2 collect_shard_2 Find the second Lumenshard Collect lumenshard_2 1
    3 collect_shard_3 Find the third Lumenshard Collect lumenshard_3 1
    4 collect_shard_4 Find the fourth Lumenshard Collect lumenshard_4 1
    5 collect_shard_5 Find the fifth Lumenshard Collect lumenshard_5 1
  5. In the Rewards list, set size to 1. Set completionMessage to "The Vale's light returns. You did it.". Set nextQuestId to sacred_glade.

Quest_SacredGlade:

  1. Right-click in Assets/Vale/Data/ > Create > Vale > Quest Data.
  2. Name the file Quest_SacredGlade.

  3. Fill in:

    Field Value
    questId sacred_glade
    title The Sacred Glade
    description Place all five Lumenshards on the altar at the Sacred Glade to restore the Vale's light.

  4. Objectives list, size 1:

    Index objectiveId description type targetId requiredCount
    0 place_all_shards Place all 5 Lumenshards on the altar Place altar_sacred_glade 5

Dialogue data (6 assets)

Create one DialogueData asset per NPC. The Elder needs a quest-offer dialogue; each Keeper needs a greeting, hint, and farewell.

  1. Right-click in Assets/Vale/Data/ > Create > Vale > Dialogue Data.
  2. Name it Dialogue_Elder_Default.
  3. Fill in:
    • dialogueId: elder_default
    • npcId: fairy_elder
    • startNodeId: greeting

  4. In the Nodes list, set size to 3:

    Index nodeId speakerName text nextNodeId
    0 greeting Fairy Elder Ah, a traveller. You have come at a strange time. The Vale's light is fading, and we need your help. hint
    1 hint Fairy Elder Five Lumenshards were lost when the first darkness came. Find them, speak to the keepers who guard them, and bring them to the Sacred Glade at the Vale's heart. farewell
    2 farewell Fairy Elder Go now, traveller. The forest will guide you. The keepers will share their memories with you. (leave empty)

    On node greeting, add one choice:

    • label: I will help you
    • nextNodeId: hint
    • advanceObjective: main_quest/talk_elder

Repeat for each Keeper. Use this naming convention:

File name dialogueId npcId
Dialogue_Keeper1_Default keeper1_default keeper_1
Dialogue_Keeper2_Default keeper2_default keeper_2
Dialogue_Keeper3_Default keeper3_default keeper_3
Dialogue_Keeper4_Default keeper4_default keeper_4
Dialogue_Keeper5_Default keeper5_default keeper_5

For each Keeper, use 3 nodes: greeting, hint, farewell. The hint node should mention the location of their shard (e.g. “My shard rests beyond the eastern ridge, past the old oaks”). The farewell node ends the dialogue.

NPC data (6 assets)

  1. Right-click in Assets/Vale/Data/ > Create > Vale > NPC Data.
  2. Name the first one NPC_Elder.

  3. Fill in:

    Field Value
    npcId fairy_elder
    displayName Fairy Elder
    isQuestGiver true
    questsOffered Add 1 entry: main_quest
    wanderRadius 2
    wanderSpeed 0.5
    wanderInterval 8
  4. In the Dialogues list, set size to 1 and drag the Dialogue_Elder_Default asset into the slot.

Repeat for the five Keepers:

File name npcId displayName isQuestGiver wanderRadius
NPC_Keeper1 keeper_1 Keeper of the East false 4
NPC_Keeper2 keeper_2 Keeper of the West false 4
NPC_Keeper3 keeper_3 Keeper of the South false 4
NPC_Keeper4 keeper_4 Keeper of the North false 4
NPC_Keeper5 keeper_5 Keeper of the Grove false 4

For each, set wanderSpeed to 1.2 and wanderInterval to 4. Drag the corresponding Dialogue_Keeper*_Default asset into their Dialogues list.

Collectible data (5 assets)

  1. Right-click in Assets/Vale/Data/ > Create > Vale > Collectible Data.
  2. Name the first one Collectible_Lumenshard1.

  3. Fill in:

    Field Value
    collectibleId lumenshard_1
    displayName Lumenshard I
    description A shard of crystallized fairy light, warm to the touch.
    value 10
    pickupPrompt Press E to pick up
  4. Leave the icon field empty for now (you can assign a sprite later).

Repeat for Lumenshards 2 through 5:

File name collectibleId displayName
Collectible_Lumenshard2 lumenshard_2 Lumenshard II
Collectible_Lumenshard3 lumenshard_3 Lumenshard III
Collectible_Lumenshard4 lumenshard_4 Lumenshard IV
Collectible_Lumenshard5 lumenshard_5 Lumenshard V

Run the editor menu items

The scene is built procedurally by four editor scripts. Each one creates specific GameObjects in the currently open scene. Make sure you have a scene open (File > New Scene, or open Assets/Vale/Scenes/FairyVale.unity if it exists) before running these.

Run them in this order:

1. Vale > Build Vale Scene

Go to Vale > Build Vale Scene in the top menu bar.

This creates the base scene hierarchy: a Lighting group with an HDRP Volume, a Terrain group (Unity Terrain object with default grass splatting), a SacredGlade group with an Altar child (5 slot positions), a Player Start empty GameObject at the spawn point, and a Main Camera with a Cinemachine Virtual Camera.

You should see the new objects appear in the Hierarchy window. If the terrain looks flat and grey, that is normal at this stage. The HDRI from Step 5 will provide the lighting.

2. Vale > Populate Forest

Go to Vale > Populate Forest.

This script scatters tree and mushroom prefabs across the terrain. It references prefabs from Assets/Vale/Prefabs/Vegetation/ (the Kenney Nature Kit folder you imported in Step 5). If you skipped the Kenney import, the script will log a warning to the console and place fewer objects.

You should see hundreds of trees and mushrooms appear on the terrain. The placement is random but seeded, so running it again produces the same layout. If you want a different layout, delete the Foliage group in the Hierarchy and run the menu item again.

3. Vale > Place Lumenshards

Go to Vale > Place Lumenshards.

This creates five Lumenshard GameObjects in cleared circular glades spread around the forest. Each shard is a small glowing sphere (using an HDRP Unlit material) with a point light and a particle emitter for fairy dust. Each one references the corresponding CollectibleData asset you created in Step 6.

You should see five glowing orbs in the Hierarchy under a Collectibles group. If you cannot see them in the scene, they may be far from the camera. Select one in the Hierarchy and press F to frame it.

4. Vale > Place NPCs

Go to Vale > Place NPCs.

This places the Fairy Elder near the Player Start position and the five Keepers near their respective Lumenshard glades. Each NPC is a GameObject with a FairyNPC component, a capsule collider, and a NPCData reference.

You should see six NPC objects in the Hierarchy under an NPCs group. The Elder will be the closest to the spawn point.

After running all four menu items, go to File > Save Scene As and save it as Assets/Vale/Scenes/FairyVale.unity.

Wire the UI Canvas

The game uses UGUI (Unity’s built-in UI system) for all HUD elements. You need to create a Canvas and attach the five UI scripts to child objects.

Create the Canvas

  1. Go to GameObject > UI > Canvas.
  2. Unity creates a Canvas GameObject and a EventSystem GameObject.
  3. Select the Canvas in the Hierarchy.
  4. In the Inspector, set Render Mode to Screen Space - Overlay. (This is the default, but confirm it.)
  5. Set UI Scale Mode to Scale With Screen Size and set Reference Resolution to 1920 x 1080.

Create child panels

Right-click the Canvas in the Hierarchy and create five empty child GameObjects. For each one, add the appropriate UI script component.

Child name Script to add (via Add Component) What it controls
HUD HUDController Shard count, quest tracker, health (if added later)
QuestLog QuestLogUI Tab-toggle quest log overlay
Dialogue DialogueUI Speaker name, dialogue text, choice buttons
InteractionPrompt InteractionPromptUI “Press E to talk” / “Press E to pick up” prompt at screen bottom
Pause PauseMenuUI Pause overlay with Resume, Save, Quit buttons

For each child:

  1. Select it in the Hierarchy.
  2. In the Inspector, click Add Component.
  3. Type the script name (e.g. HUDController) and click it to add.
  4. The script’s serialized fields will appear in the Inspector. Drag the appropriate references from the scene into them.

Reference wiring table:

Script Field Drag in
HUDController shardCountText A Text (TMP) component (create via right-click > UI > Text)
HUDController questTrackerText A second Text (TMP) component
QuestLogUI questLogPanel An empty GameObject with an Image component (background)
QuestLogUI questEntriesContainer A Content Size Fitter or Vertical Layout Group parent
DialogueUI speakerNameText A Text (TMP) component
DialogueUI dialogueText A Text (TMP) component
DialogueUI choiceButtons A Vertical Layout Group parent for choice Button objects
InteractionPromptUI promptText A Text (TMP) component
InteractionPromptUI promptImage An Image component (background behind the text)
PauseMenuUI pausePanel An empty GameObject with an Image component
PauseMenuUI resumeButton A Button object
PauseMenuUI quitButton A Button object

Tip: To create UI elements quickly, right-click a panel in the Hierarchy > UI > Text - TextMeshPro for text, UI > Image for backgrounds, UI > Button for buttons. Unity will auto-arrange them with layout groups.

If the UI scripts have not been created yet (check Assets/Vale/Scripts/UI/), the Add Component search will not find them. In that case, skip this step for now. The game is still playable without UI; you can add the canvas later once the scripts are in place.

Save the Input asset reference

The InputManager component needs the ValeInput.inputactions asset assigned. Without it, none of the game’s input will work.

  1. In the Hierarchy, find the GameManager GameObject. If you do not see one, the GameManager script auto-creates its subsystems in Awake(), so the InputManager will be a child of GameManager. Look for a child named InputManager.
  2. Select the InputManager object.
  3. In the Inspector, find the Input Actions field (under the “Input” header).
  4. Drag Assets/Vale/Settings/ValeInput.inputactions from the Project window into that field.
  5. Save the scene (Ctrl+S).

If you cannot find an InputManager object in the scene, select the GameManager and check the Input Manager field in its Inspector. GameManager.EnsureSubsystems() creates the InputManager automatically on first Play, but it is cleaner to create it manually:

  1. Right-click GameManager > Create Empty. Name it InputManager.
  2. Add the InputManager component (Add Component > search “InputManager”).
  3. Drag the ValeInput.inputactions asset into the Input Actions field.
  4. Drag the InputManager object into the GameManager’s Input Manager serialized field.

Press Play

  1. Make sure FairyVale.unity is the active scene (double-click it in the Project window if needed).
  2. Click the Play button at the top-center of the editor (the triangle icon).

What should happen:

If everything works, congratulations. You have a playable prototype of VALE.

Troubleshooting

“The scene looks dark / all black”

HDRP is not set as the active render pipeline, or no HDRI is assigned.

“Scripts are not compiling (red errors in Console)”

Check the Console window (Window > General > Console) for the exact error message. Common causes:

“Input does not work (keys do nothing)”

The InputManager does not have the input asset assigned.

“UI is invisible”

The Canvas render mode is wrong or the UI elements have no size.

“I cannot find the ‘Vale’ menu in the top menu bar”

The editor scripts in Assets/Vale/Scripts/Editor/ have not compiled.

“The forest populator placed nothing”

The script could not find any tree or mushroom prefabs.

“The game loads but the player cannot move”

Next steps

This site is open source. Improve this page.