SchoolDop Modding Guide

1. Player Customization

The player is configured in player.json. This file controls the player character's base appearance and starting stats.

{
  "player": "female",
  "reputation": 0,
  "breastSize": 0.75,
  "hairstyleId": 4
}

Player Fields

• player: Gender of the player character. Accepted values: male, female
• reputation: Starting social reputation value (integer)
• breastSize: Chest size multiplier for the player model (float, e.g. 0.75)
• hairstyleId: ID of the hairstyle to apply. Must match a valid ID in hairstyles.json (see Section 3)

2. Students Customization

Students are defined in students.json. Each entry includes identity, appearance, routine, and social attributes. Both male and female students are fully supported. You can freely add new students by creating new entries with unique IDs, or remove existing ones by deleting their entry — the game will load exactly whoever is in the array.

{
  "id": 1,
  "name": "Haruto Katou",
  "gender": "Male",
  "type": "Student",
  "club": "Computer_Science",
  "socialReputation": 35,
  "loveTargetID": -1,
  "faceMaterial": "Male/MaleFace_Red",
  "hairMaterial": "Male/MaleHair_Red",
  "hairstyleID": 0,
  "chestSize": 0,
  "routineID": "1"
}

2.1 Student Fields

• id: Unique integer identifier for the student
• name: Display name
• gender: Male or Female
• type: Student or Teacher
• club: Club membership (see valid values in Section 5)
• socialReputation: Reputation score (integer, can be negative)
• loveTargetID: ID of the love interest, or -1 for none
• faceMaterial: Path to the face texture (e.g. Male/MaleFace_Red, Female/FemaleFace_Black)
• hairMaterial: Path to the hair texture (e.g. Male/MaleHair_Green, Female/FemaleHair_Yellow)
• hairstyleID: ID of the hairstyle shape from hairstyles.json (see Section 3)
• chestSize: Chest size multiplier for the character model (float). Use 0 for male characters
• routineID: String ID referencing an entry in routines.json

2.2 Appearance

Material paths now use gender-based subfolders. Use Male/ for male characters and Female/ for female characters.

• Male materials: Male/MaleFace_[Color] and Male/MaleHair_[Color]
• Female materials: Female/FemaleFace_[Color] and Female/FemaleHair_[Color]
• Hair / Face Colors: Standard, Black, Red, Green, Blue, Yellow, Cyan, Purple
• Texture Replacement: Add New prefix to your texture names. Example: NewFemaleHair_Blue.png

3. Hairstyle Customization

Hairstyle shapes are defined in hairstyles.json. Each hairstyle has an id and a list of parts, each describing a hair bone's local transform. The hairstyleID field in students.json and player.json references these IDs.

{
  "hairstyles": [
    {
      "id": 0,
      "parts": [
        {
          "objectName": "FrontHair",
          "localPosition": { "x": 0.0, "y": -0.08, "z": 0.13 },
          "localRotation": { "x": 0.0, "y": 0.0, "z": 0.0 },
          "localScale": { "x": 1.0, "y": 1.0, "z": 1.0 },
          "children": []
        }
      ]
    }
  ]
}

3.1 Hairstyle Part Fields

• objectName: The exact name of the hair bone/object to transform. Valid names: BackHair1, FrontHair, LeftHair1, LeftHair2, LeftHair3, RightHair1, RightHair2, RightHair3
• localPosition: Position offset relative to the parent bone (x, y, z floats)
• localRotation: Euler rotation in degrees (x, y, z floats)
• localScale: Scale multiplier per axis. Set to { "x": 0, "y": 0, "z": 0 } to hide a part
• children: Array of nested parts following the same structure, for multi-segment hair chains

3.2 Built-in Hairstyle IDs

• ID 0: Standard — back hair, front hair, and full side tails (LeftHair1+2, RightHair1+2)
• ID 1: Big back — BackHair1 at 2× scale, side parts hidden
• ID 2: Tall front — FrontHair taller (1.5× Y scale), no back hair, shorter side tails
• ID 3: Small back — BackHair1 at 0.75× scale, side parts hidden
• ID 4: Long tails — Three-segment side chains (Hair1→Hair2→Hair3), short front hair, no back hair

4. Routine Customization

Routines are defined in routines.json. Each entry includes time, destination, pause duration, look direction, and separate animations for movement and arrival.

{
  "hour": 7,
  "minute": 50,
  "isPM": false,
  "destination": "Sit 1 1",
  "pauseSeconds": 0,
  "lookDirectionName": "East",
  "animationOnMove": "none",
  "animationOnArrival": "sit"
}

Routine Fields

• hour / minute / isPM: Time of the action (12-hour format; set isPM: true for afternoon)
• destination: Exact location name (case-sensitive — see Section 6)
• pauseSeconds: Wait duration in seconds after arrival
• lookDirectionName: Direction the character faces. Valid values: North, South, East, West
• animationOnMove: Animation played while moving
• animationOnArrival: Animation triggered when reaching the destination

Valid Animation Values

• none
• idle
• sit

5. NPC Reaction Messages

Reaction messages are defined in reactions.json. These are the dialogue lines NPCs speak when they notice suspicious behavior from the player.

{
  "bloodMessage": "Why are you covered in blood?!",
  "weaponMessage": "Why are you carrying a weapon?",
  "bloodAndWeaponMessage": "What the hell happened to you?!",
  "professorMessage": "What are you doing? Stop right now!",
  "corpseMessage": "Oh no... there's a body here!"
}

Reaction Fields

• bloodMessage: Spoken when the player is visibly covered in blood
• weaponMessage: Spoken when the player is seen carrying a weapon
• bloodAndWeaponMessage: Spoken when both conditions are met simultaneously
• professorMessage: Spoken by a teacher/professor when intervening
• corpseMessage: Spoken when an NPC discovers a dead body

6. NPC Type and Club Limitations

• Types: Student and Teacher — both fully functional
• Student Features: Full routine system, animations, clubs, social reputation, hairstyles, chest size
• Teacher Features: Full routine system, movement, gender support, hairstyles, and texture customization — same flexibility as students. Clubs and social mechanics are not applicable
• Gender: Both Male and Female are supported for both Students and Teachers
• Valid Clubs: None, Cooking, Drama, Sports, Science, Occult, Computer_Science

7. Environment Modding

Object placement in the environment is defined in objects.json. This file covers the entire scene — any object in the game world can be repositioned, rotated, or rescaled. Just use the exact in-engine object name and the game will apply your transforms automatically.

{
  "objects": [
    {
      "name": "Name1",
      "position": { "x": 1, "y": 2, "z": 3 },
      "rotation": { "x": 0, "y": 90, "z": 0 },
      "scale": { "x": 2, "y": 2, "z": 2 }
    }
  ]
}

Object Fields

• name: The exact name of the object in the scene (case-sensitive)
• position: World-space position (x, y, z floats)
• rotation: Euler rotation in degrees (x, y, z floats)
• scale: Scale multiplier per axis (x, y, z floats)

Texture Replacement

Currently, only specific textures can be replaced via StreamingAssets:

• Buildings/Vegetations/T_bark02.png

Valid Routine Location Points

Destination names in routines must match exactly (capitalization matters):

• Locker L1 · Locker L2 · Locker L3 · Locker L4
• Locker R1 · Locker R2 · Locker R3 · Locker R4
• Sit 1 1 · Sit 1 2 · Sit 1 3 · Sit 1 4 · Sit 1 5 · Sit 1 6 · Sit 1 7 · Sit 1 8
• Garden 1 · Garden 2 · Garden 3 · Garden 4
• School 1 · School 2 · School 3 · School 4
• Professor 1
• Professor Room
• FleePoint

8. Lua Scripting NEW

⚠️ Lua scripting is experimental in v0.5.x. The API may change or break between updates. Use it for testing and feedback — avoid building large mods until a stable release.

SchoolDop supports Lua mods via the MoonSharp interpreter. Lua scripts can react to game events, spawn and manipulate objects, control NPCs, set up proximity triggers, and run timed logic — all without recompiling the game.

8.1 File Setup

Place all .lua files inside the StreamingAssets/Scripts/ folder. The game loads every file in that folder alphabetically at startup. Custom 3D models (AssetBundles) go in StreamingAssets/Bundles/.

8.2 Event Hooks

Define any of the following global functions in your Lua file and the game will call them automatically:

Hook	When it's called	Arguments
OnStart()	Once, right after all mods are loaded	—
OnUpdate()	Every frame	—
OnPlayerUpdate(player)	Every frame (only when the player exists)	player — the player GameObject
OnNPCUpdate(npc)	Every frame, once per NPC	npc — an NPC GameObject
OnCustomEvent(name, ...)	When the game fires a custom C# event	name (string) + optional extra args

-- minimal example
function OnStart()
    Game:Print("Mod loaded!")
end

function OnPlayerUpdate(player)
    if Game:IsPlayerRunning() then
        Game:Print("Player is running!")
    end
end

8.3 Game API Overview

All functionality is exposed through the global Game object. Below is a full reference grouped by category.

Function	Returns	Description
Game:NewVector3(x, y, z)	Vector3	Creates a 3D position/direction value
Game:NewColor(r, g, b, a)	Color	Creates an RGBA color (values 0–1)
Game:NewRotation(x, y, z)	Quaternion	Creates a rotation from Euler degrees

Function	Returns	Description
Game:Print(msg)	void	Log an info message (prefixed with [Lua])
Game:Warn(msg)	void	Log a warning message
Game:Error(msg)	void	Log an error message

Function	Returns	Description
Game:SpawnCube(pos, scale, color)	GameObject	Spawns a colored cube primitive
Game:SpawnSphere(pos, scale, color)	GameObject	Spawns a sphere primitive
Game:SpawnCapsule(pos, scale, color)	GameObject	Spawns a capsule primitive
Game:SpawnCylinder(pos, scale, color)	GameObject	Spawns a cylinder primitive
Game:SpawnPlane(pos, scale, color)	GameObject	Spawns a flat plane primitive
Game:CreateEmpty(name, position)	GameObject	Creates a named empty object at a position
Game:CreateEmpty(name)	GameObject	Creates a named empty object at origin
Game:LoadModel(bundle, asset, pos)	GameObject	Instantiates a prefab from an AssetBundle in StreamingAssets/Bundles/
Game:LoadModelRotated(bundle, asset, pos, eulerRot)	GameObject	Same as above with an initial rotation

Function	Returns	Description
Game:Find(name)	GameObject	Finds a scene object by exact name
Game:FindByTag(tag)	List	Returns all objects with a given Unity tag
Game:GetPlayer()	GameObject	Returns the player's GameObject
Game:GetAllNPCs()	List	Returns a list of all NPC GameObjects
Game:GetAllNPCsInRange(center, range)	List	Returns NPCs within range units of center

Function	Returns	Description
Game:SetPosition(obj, pos)	void	Teleports an object to a world position
Game:GetPosition(obj)	Vector3	Returns the object's world position
Game:SetRotation(obj, euler)	void	Sets rotation from Euler degrees (Vector3)
Game:SetScale(obj, scale)	void	Sets the object's local scale
Game:LookAt(obj, target)	void	Rotates obj to face another GameObject
Game:LookAtPosition(obj, pos)	void	Rotates obj to face a world position
Game:GetForward(obj)	Vector3	Returns the object's forward direction vector
Game:SetParent(child, parent)	void	Parents child under parent (keeps world position)
Game:Unparent(obj)	void	Detaches an object from its parent

Function	Returns	Description
Game:Distance(a, b)	float	Distance between two GameObjects
Game:DistanceV3(a, b)	float	Distance between two Vector3 positions
Game:IsNear(a, b, maxDist)	bool	True if two objects are within maxDist
Game:IsPlayerNear(obj, maxDist)	bool	True if the player is within maxDist of obj
Game:DirectionTo(from, to)	Vector3	Normalized direction vector from one object to another

Function	Returns	Description
Game:AddRigidbody(obj, useGravity)	Rigidbody	Adds a physics Rigidbody
Game:GetRigidbody(obj)	Rigidbody	Gets the existing Rigidbody
Game:AddBoxCollider(obj, center, size)	BoxCollider	Adds a box collider
Game:AddSphereCollider(obj, radius)	SphereCollider	Adds a sphere collider
Game:AddCapsuleCollider(obj, radius, height)	CapsuleCollider	Adds a capsule collider
Game:AddTrigger(obj, center, size)	BoxCollider	Adds a box collider set as trigger (isTrigger = true)
Game:AddNavMeshAgent(obj, speed, radius)	NavMeshAgent	Adds a NavMesh navigation agent
Game:GetNavMeshAgent(obj)	NavMeshAgent	Gets the existing NavMeshAgent
Game:SetNavDestination(obj, dest)	void	Moves an agent toward a world position
Game:StopNav(obj)	void	Stops the agent and clears its path
Game:AddAnimator(obj)	Animator	Adds an Animator component
Game:GetAnimator(obj)	Animator	Gets the existing Animator

Function	Returns	Description
Game:AddLight(obj, type, color, intensity, range)	Light	Adds a light. type accepts: "point", "spot", "directional", "area"

Function	Returns	Description
Game:SetColor(obj, color)	void	Sets the main albedo color of an object's material
Game:SetMaterial(obj, color, metallic, smoothness)	void	Replaces the material with a new Standard shader material
Game:SetEmissive(obj, color)	void	Enables emission and sets the glow color

Function	Returns	Description
Game:SetAnimBool(obj, param, value)	void	Sets a boolean parameter
Game:SetAnimFloat(obj, param, value)	void	Sets a float parameter
Game:SetAnimInt(obj, param, value)	void	Sets an integer parameter
Game:SetAnimTrigger(obj, param)	void	Fires a trigger parameter
Game:GetAnimBool(obj, param)	bool	Returns the current value of a boolean parameter
Game:GetAnimFloat(obj, param)	float	Returns the current value of a float parameter

Function	Returns	Description
Game:PauseNPC(obj)	void	Temporarily freezes an NPC's routine
Game:ResumeNPC(obj)	void	Resumes a paused NPC's routine
Game:StopNPC(obj)	void	Permanently stops an NPC's routine for the session
Game:IsNPCPanicked(obj)	bool	Returns true if the NPC is currently panicked
Game:IsNPCReacting(obj)	bool	Returns true if the NPC is currently reacting to something

Function	Returns	Description
Game:IsPlayerRunning()	bool	True if the player is currently running
Game:IsPlayerCrouching()	bool	True if the player is currently crouching
Game:GetPlayerSpeed()	float	Returns the player's current movement speed (m/s)

Function	Returns	Description
Game:AddForce(obj, force)	void	Applies an impulse force to an object's Rigidbody
Game:Raycast(origin, direction, maxDist)	bool	Returns true if the ray hits any collider
Game:RaycastGetObject(origin, direction, maxDist)	GameObject	Returns the first GameObject hit by the ray, or nil

Function	Returns	Description
Game:Destroy(obj)	void	Removes an object from the scene immediately
Game:DestroyAfter(obj, seconds)	void	Removes an object after a delay

Function	Returns	Description
Game:Wait(seconds, callback)	void	Calls callback once after seconds
Game:SetInterval(interval, callback)	int	Calls callback every interval seconds. Returns a timer ID
Game:CancelTimer(id)	void	Stops a repeating timer by its ID

-- run something after 3 seconds
Game:Wait(3.0, function()
    Game:Print("3 seconds passed!")
end)

-- repeat every 5 seconds, then stop after 30s
local myTimer = Game:SetInterval(5.0, function()
    Game:Print("tick")
end)

Game:Wait(30.0, function()
    Game:CancelTimer(myTimer)
    Game:Print("interval stopped")
end)

Function	Returns	Description
Game:OnPlayerNear(target, radius, callback)	void	One-shot: fires once when the player enters radius around target, then unregisters itself
Game:OnPlayerNearContinuous(target, radius, callback)	void	Continuous: fires every frame while the player is within radius
Game:OnPlayerEnterExit(target, radius, onEnter, onExit)	void	Fires onEnter when the player enters and onExit when they leave. Either argument can be nil
Game:OnNPCNear(target, radius, callback)	void	Fires once per unique NPC that enters radius around target

function OnStart()
    local marker = Game:SpawnCube(
        Game:NewVector3(5, 0, 10),
        Game:NewVector3(0.5, 0.5, 0.5),
        Game:NewColor(1, 0, 0, 1)
    )

    -- one-shot: fires once when player steps near
    Game:OnPlayerNear(marker, 2.0, function()
        Game:Print("Player reached the marker!")
        Game:Destroy(marker)
    end)

    -- enter / exit zone
    local zone = Game:Find("GardenArea")
    Game:OnPlayerEnterExit(zone, 5.0,
        function() Game:Print("Entered garden") end,
        function() Game:Print("Left garden")   end
    )
end

Function	Returns	Description
Game:Random(min, max)	float	Random float in [min, max]
Game:RandomInt(min, max)	int	Random integer in [min, max)
Game:Time()	float	Seconds since the game started (Time.time)
Game:DeltaTime()	float	Time elapsed since last frame (Time.deltaTime)
Game:RandomPointAround(center, radius)	Vector3	Random position on the XZ plane within radius of center
Game:IsNull(obj)	bool	Safe null-check for GameObjects (use instead of obj == nil)
Game:GetName(obj)	string	Returns the object's name
Game:SetName(obj, name)	void	Renames the object
Game:SetActive(obj, active)	void	Enables or disables an object in the scene
Game:IsActive(obj)	bool	Returns true if the object is active in the hierarchy

8.4 Current Limitations

The following actions are not possible with the current Lua API:

• Directly controlling player movement, input, or camera
• Modifying NPC routines at runtime (add/remove schedule entries) — use routines.json for that
• Accessing or changing a student's social reputation or love target at runtime
• Creating new UI elements or HUD overlays
• Playing audio clips or music
• Saving data between sessions (no persistent storage API yet)
• Communicating between two separate Lua scripts directly (all scripts share the same Lua environment, so global variables work, but there's no explicit import/require)
• Using Unity coroutines directly — use Game:Wait() and Game:SetInterval() instead

8.5 Full Example Mod

-- example_mod.lua
-- Spawns a glowing orb. When the player gets close it explodes
-- into smaller spheres and logs a message every 10 seconds.

local orb
local tickTimer

function OnStart()
    -- spawn the orb above the garden
    local pos = Game:NewVector3(0, 1.5, 8)
    local scale = Game:NewVector3(0.6, 0.6, 0.6)
    local color = Game:NewColor(0.2, 0.8, 1, 1)

    orb = Game:SpawnCube(pos, scale, color)
    Game:SetEmissive(orb, Game:NewColor(0, 0.5, 1, 1))
    Game:SetName(orb, "GlowOrb")

    -- start a repeating log
    tickTimer = Game:SetInterval(10.0, function()
        Game:Print("Orb is still alive at t=" .. Game:Time())
    end)

    -- explode when the player steps within 2 units
    Game:OnPlayerNear(orb, 2.0, function()
        Explode()
    end)
end

function Explode()
    if Game:IsNull(orb) then return end

    local center = Game:GetPosition(orb)
    Game:Destroy(orb)
    Game:CancelTimer(tickTimer)

    -- spawn 6 small debris spheres
    for i = 1, 6 do
        local offset = Game:RandomPointAround(center, 1.5)
        local debris = Game:SpawnSphere(
            offset,
            Game:NewVector3(0.2, 0.2, 0.2),
            Game:NewColor(Game:Random(0,1), Game:Random(0,1), Game:Random(0,1), 1)
        )
        Game:DestroyAfter(debris, 3.0)
    end

    Game:Print("Orb exploded!")
end

9. Tips & Best Practices

• Backup all JSON files before editing
• Use exact names for textures and location points — capitalization matters
• Add New prefix for custom replacement textures (e.g. NewFemaleHair_Cyan.png)
• Use chestSize: 0 for all male characters
• Hairstyle IDs must exist in hairstyles.json — invalid IDs will fall back to default
• Test changes in Unity Editor before sharing mods
• In Lua, avoid heavy logic in OnUpdate / OnNPCUpdate — prefer Game:SetInterval() for periodic checks
• Use Game:IsNull(obj) instead of obj == nil for safe null checks on GameObjects
• Name your spawned objects with Game:SetName() so they're easy to Game:Find() later
• Use alphabetical file prefixes (e.g. 00_, 01_) to control Lua mod load order