Planetary Instability Model: Complete Unity Setup Walkthrough

Planetary Instability Model PIM - Copyright (C) 2025 James Pacha

This guide provides a comprehensive, step-by-step walkthrough for setting up, installing, and running your Unity project with the N-body and Earth internal dynamics simulation. It consolidates all the necessary information for a smooth setup, including all the C# files we've developed.

Estimated Time: 15-30 minutes (depending on Unity download speed and familiarity).

Step 1: Prerequisites

Unity Hub: Download and install Unity Hub from the official Unity website: https://unity.com/download

Unity Editor: Through Unity Hub, install a Unity Editor version. It's recommended to use the latest stable LTS (Long Term Support) version (e.g., Unity 2022 LTS or 2023 LTS). Make sure to include the "Windows Build Support (IL2CPP)" and "Mac Build Support (IL2CPP)" modules if you plan to build for those platforms.

Step 2: Create a New Unity Project

Open Unity Hub.

Click on "New Project".

Select the "3D Core" template.

In the "Project name" field, enter a name for your project (e.g., PlanetaryInstabilitySim).

Choose a suitable "Location" on your computer.

Click "Create Project".

Unity Editor will open and create your new project. This may take a few minutes.

Step 3: Create and Populate C# Scripts

You will create eleven C# scripts in your Unity project and copy the provided code into each.

In the Unity Editor's Project window (usually at the bottom, showing the Assets folder), right-click -> Create -> C# Script.

Name the script precisely as indicated below.

Double-click the newly created .cs file to open it in your code editor (e.g., Visual Studio).

Copy the code from the corresponding immersive artifact (the one provided in our conversation) and paste it into the .cs file, overwriting all default content. Save the file (Ctrl+S or Cmd+S).

Repeat steps 1-4 for the following scripts, using their exact names and the code from the respective immersive artifacts:

Vector3d.cs

Purpose: Custom struct for 3D vectors using double-precision floating-point numbers, crucial for astronomical accuracy.

Code Source: Use the code from the vector_3d immersive artifact I provided.

PlanetController.cs

Purpose: Defines physical properties (mass, position, velocity, acceleration) for each celestial body.

Code Source: Use the code from the planet_controller immersive artifact I provided.

NBodySimulator.cs

Purpose: Manages the overall N-body gravitational simulation, calculates forces, updates states, and handles data logging.

Code Source: Use the code from the nbody_simulator immersive artifact I provided.

EarthConstantsAndCalculations.cs

Purpose: Centralizes all fundamental empirical constants for Earth (WGS 84 data, Love numbers, layer radii, etc.) and provides common calculation methods.

Code Source: Use the code from the earth_constants_calculations_full immersive artifact I provided.

EarthCoreCalculations.cs

Purpose: Centralizes empirical data and calculations specifically for the Earth's Inner and Outer Core, including thermal and compositional dynamics.

Code Source: Use the code from the earth_core_calculations_full_terms immersive artifact I provided.

OceanCalculations.cs

Purpose: Centralizes empirical data and calculations specifically for the Earth's oceans (hydrosphere).

Code Source: Use the code from the ocean_calculations immersive artifact I provided.

EarthLayerProperties.cs

Purpose: A simple data holder for the empirical properties of a single Earth layer, attached to each nested sphere.

Code Source: Use the code from the earth_layer_properties immersive artifact I provided.

EarthInternalStructure.cs

Purpose: Programmatically creates the nested spherical layers of Earth's interior based on empirical data and attaches EarthLayerProperties to each.

Code Source: Use the code from the earth_internal_structure_full immersive artifact I provided.

CoreGridPoint.cs

Purpose: Represents a single discretized point within the Earth's outer core, holding local physical properties for fluid dynamics and magnetic field calculations.

Code Source: Use the code from the core_grid_point_full immersive artifact I provided.

CoreDynamicsSimulator.cs

Purpose: Manages the simulation of the Earth's outer core fluid dynamics, including magnetic field, temperature, and compositional anomaly evolution.

Code Source: Use the code from the core_dynamics_simulator_full immersive artifact I provided.

PolarIceCapModel.cs

Purpose: Manages the dynamic mass and moment of inertia calculations for the polar ice caps.

Code Source: Use the code from the polar_ice_cap_model immersive artifact I provided.

TrenchInstabilitySimulator.cs

Purpose: Simulates Earth's rotational dynamics, focusing on internal mass redistribution (ice melt, liquid core) and external gravitational forces, and updates the main UI.

Code Source: Use the code from the trench_simulator_final immersive artifact I provided.

PlanetaryInstabilityVisualizer.cs

Purpose: Visualizes the Earth spheroid, handles camera controls, simulates tidal effects via mesh deformation, and provides interactive data readouts.

Code Source: Use the code from the planetary_instability_visualizer_full immersive artifact I provided.

Important: After creating all thirteen scripts and pasting their code, ensure there are no compilation errors in Unity's Console window. If there are, double-check that you've copied the correct code for each script and that all script names match exactly.

Step 4: Create and Configure Materials

You'll need materials for the celestial bodies and for Earth's internal layers.

In the Project window, right-click -> Create -> Material.

Create the following materials (name them exactly as suggested):

SunMaterial (Set its Albedo color to a bright yellow/orange).

EarthMaterial (For the base Earth prefab, e.g., a general rocky planet texture/color).

MoonMaterial (For the Moon prefab, e.g., a light gray).

InnerCoreMaterial (e.g., bright yellow/white).

OuterCoreMaterial (e.g., orange/red).

LowerMantleMaterial (e.g., dark red/brown).

AsthenosphereMaterial (e.g., slightly lighter red/brown).

LithosphereMaterial (e.g., dark gray).

CrustMaterial (e.g., light brown/green).

WaterMaterial (e.g., blue). For this, change the Rendering Mode in the Inspector from Opaque to Fade or Transparent to make it see-through.

IceMaterial (e.g., white/light blue). Also set Rendering Mode to Fade or Transparent.

Step 5: Set up the Scene GameObjects

A. Create the NBodySimulatorManager
This will be your central controller for the solar system simulation.

In the Hierarchy window (usually on the left), right-click -> Create Empty.

Rename this new GameObject to NBodySimulatorManager.

Select NBodySimulatorManager in the Hierarchy.

In the Inspector window (usually on the right), click Add Component and search for NBodySimulator. Add the script.

In the NBodySimulator component in the Inspector, drag the materials you created into their respective slots:

Sun Prefab: Drag a default Sphere primitive or a custom Sun model here.

Earth Prefab: Drag a default Sphere primitive or a custom Earth model here.

Moon Prefab: Drag a default Sphere primitive or a custom Moon model here.

Configure Simulation Parameters:

Simulation Time Step (s): Start with 60 (for 1 minute per physics step). You can reduce this for more accuracy (e.g., 10 or 1), but it will slow down the simulation.

Distance Scale (m per Unity Unit): Keep this at 1e9 (1,000,000,000 meters per Unity unit). This allows you to use real-world distances in meters for initial conditions while scaling them visually in Unity.

Enable Data Logging: Check this box if you want to log simulation data to a CSV file.

Log File Name: You can keep the default or change it (e.g., solar_system_data.csv).

B. Create the PlanetaryModelManager
This will handle the Earth's internal visualization, UI, and camera.

In the Hierarchy window, right-click -> Create Empty.

Rename this new GameObject to PlanetaryModelManager.

Select PlanetaryModelManager in the Hierarchy.

In the Inspector, click Add Component and search for PlanetaryInstabilityVisualizer. Add the script.

In the PlanetaryInstabilityVisualizer component, assign the following references:

Main Camera: Drag your Main Camera GameObject (from Hierarchy) here.

Water Material: Drag your WaterMaterial here.

Land Material: Drag your CrustMaterial here (or another material you prefer for the visible surface).

Enable Tidal Deformation: Ensure this is checked if you want to see the tidal effects.

C. Set up UI Text Elements
You'll need two UI Text elements to display simulation data and layer information.

In the Hierarchy, right-click -> UI -> Text - TextMeshPro. (If prompted, import TMP Essentials).

Rename this GameObject to GeneralInfoText.

Adjust its Rect Transform (e.g., anchor to top-left, set position, width, height) and Font Size to be clearly visible.

Repeat steps 1-3 to create another TextMeshPro GameObject, naming it LayerInfoText. Position it appropriately (e.g., below GeneralInfoText).

Select PlanetaryModelManager again.

In the PlanetaryInstabilityVisualizer component, drag GeneralInfoText to the General Info Text slot and LayerInfoText to the Layer Info Text slot.

Step 6: Run the Simulation for the First Time (Initial Setup)

This step is crucial because the NBodySimulator will create your celestial bodies (Sun, Earth, Moon) and attach their scripts at runtime.

Click the Play button at the top of the Unity Editor.

Observe the Hierarchy window. You should see new GameObjects appear: Sun, Earth, and Moon.

Unity Console: Check the Console window for any Debug.LogError messages. If you see errors, double-check that you've copied the correct code for each script and that you've assigned all materials and prefabs correctly in the NBodySimulatorManager Inspector.

Stop the simulation by clicking the Play button again.

Step 7: Final GameObject Assignments (After First Run)

Now that the Sun, Earth, and Moon GameObjects exist in your scene (they persist after stopping Play mode), you can make the final connections.

Select your PlanetaryModelManager GameObject in the Hierarchy.

In its Inspector, under the Planetary Instability Visualizer component, find the Data Source References section. Drag the following GameObjects from your Hierarchy into their respective slots:

Earth Spheroid: Drag the Earth GameObject here.

Earth Controller: Drag the Earth GameObject here.

Sun Controller: Drag the Sun GameObject here.

Moon Controller: Drag the Moon GameObject here.

Earth Internal Structure: Drag the Earth GameObject here.

Trench Instability Simulator: Drag the Earth GameObject here.

Core Dynamics Simulator: Drag the Earth GameObject here. (This is important for the core dynamics to be linked).

Ensure Earth is on a Raycastable Layer: Make sure the "Earth" GameObject (created by NBodySimulator) is on a layer that your Physics.Raycast can detect for interactive layer information. The default Default layer works, but if you've changed it, adjust LayerMask.GetMask("Default") in PlanetaryInstabilityVisualizer.cs accordingly.

Mesh Filter: Ensure your earthSpheroid GameObject (the one named "Earth" created by NBodySimulator) has a MeshFilter component, which it should if it's a primitive sphere. This is essential for tidal deformation.

Step 8: Adjust Camera (Optional but Recommended)

The planets will be very far apart due to the distanceScale_m_per_unity_unit. You'll need to adjust your camera to view them effectively.

Select the Main Camera in the Hierarchy.

In the Inspector, adjust its Transform -> Position to a value that allows you to see the Earth (e.g., X: 0, Y: 0, Z: -3, for a close-up of Earth, or larger values to see the whole system).

Adjust its Transform -> Rotation to look towards the center (e.g., X: 0, Y: 0, Z: 0).

You might also want to adjust the Camera component's Clipping Planes -> Far value to a very high number (e.g., 100000 or 1000000) to ensure distant objects are rendered.

Step 9: Run the Simulation and Retrieve Data

Click the Play button again.

The simulation will now run with all celestial bodies interacting, Earth's internal dynamics active, and data being logged (if enabled).

To retrieve the data:

Let the simulation run for as long as you need to collect sufficient data.

Stop the simulation by clicking the Play button.

Navigate to your Unity project's root folder on your computer (the folder you chose in Step 2).

You will find a CSV file named nbody_simulation_log.csv (or whatever you set logFileName to in NBodySimulator.cs).

Open this CSV file with a spreadsheet program (like Microsoft Excel, Google Sheets, or LibreOffice Calc) to view the collected empirical data.

You now have a fully set up and running Unity simulation that generates empirical data for your Earth model, including gravitational influences, internal dynamics, ice mass changes, and visual tidal deformation.