Troubleshooting

This page covers common issues and their solutions when working with Pill.

Build Issues

Cargo Build Fails

Problem: cargo build fails with compilation errors.

Solutions:

1. Update Rust toolchain:

   rustup update

2. Clean build cache:

   cargo clean
   cargo build --release

3. Check Rust version:

   rustc --version

   Pill requires Rust 1.70 or later.

4. Verify dependencies: Make sure all path dependencies in Cargo.toml are correct:

   [dependencies]
   pill_engine = { path = "../Pill-Engine/engine/pill_engine" }

Linker Errors on Windows

Problem: Linker errors like LINK : fatal error LNK1181.

Solutions:

1. Install Visual Studio Build Tools:

   • Download from Visual Studio
   • Select "Desktop development with C++"

2. Verify MSVC is installed:

   cargo --version --verbose

   Should show host: x86_64-pc-windows-msvc

DLL Not Found Errors

Problem: "The program can't start because *.dll is missing".

Solutions:

1. Build in release mode:

   cargo build --release

2. Check DLL path: Make sure the DLL is in the same directory as the executable or in the path.

3. Rebuild dependencies:

   cargo clean
   cargo build --release

Runtime Issues

Black Screen on Startup

Problem: Window opens but shows only a black screen.

Solutions:

1. Check camera setup:

   // Ensure camera is enabled and has proper settings
   CameraComponent::builder()
       .enabled(true)  // Must be true!
       .fov(60.0)
       .clear_color(Color::new(0.5, 0.5, 0.5))
       .build()

2. Verify scene is active:

   let scene = engine.create_scene("Main")?;
   engine.set_active_scene(scene)?;  // Don't forget this!

3. Check entity has mesh and material:

   .with_component(MeshRenderingComponent::builder()
       .mesh(&mesh_handle)      // Valid handle?
       .material(&material_handle)  // Valid handle?
       .build())

4. Verify camera position: Make sure the camera can see your entities.

Crash on Startup

Problem: Application crashes immediately.

Solutions:

1. Check config.ini:

   [window]
   title = "My Game"
   width = 1280
   height = 720

2. Enable debug mode:

   cargo run  # Debug build shows more error info

3. Check resource paths:

   // Make sure files exist at these paths
   Mesh::new("Truck", "models/Truck.obj".into())  // Check: res/models/Truck.obj exists?

4. Verify all components are registered:

   engine.register_component::<TransformComponent>(scene)?;
   // Register ALL components before creating entities!

Low FPS / Performance Issues

Problem: Game runs slowly or stutters.

Solutions:

1. Build in release mode:

   cargo build --release

   Debug builds are 10-100x slower!

2. Check MSAA settings in config.ini:

   [graphics]
   msaa = 4  # Try 0 or 2 for better performance

3. Reduce polygon count:

   • Simplify 3D models
   • Use lower-resolution textures
   • Remove unnecessary entities

4. Profile your systems:

   fn my_system(engine: &mut Engine) -> Result<()> {
       let start = std::time::Instant::now();
       
       // Your code here
       
       println!("System took: {:?}", start.elapsed());
       Ok(())
   }

5. Limit entity iteration:

   // Avoid iterating all entities every frame if possible
   // Cache data when you can

Physics Issues

Objects Fall Through Floor

Problem: Dynamic objects pass through static colliders.

Solutions:

1. Check collider setup:

   // Floor (static)
   .with_component(RigidBodyComponent::builder()
       .body_type(RigidBodyType::Fixed)  // Must be Fixed!
       .build())
   .with_component(ColliderComponent::builder()
       .shape(SharedShape::cuboid(10.0, 0.5, 10.0))  // Match mesh size
       .build())
   
   // Object (dynamic)
   .with_component(RigidBodyComponent::builder()
       .body_type(RigidBodyType::Dynamic)
       .build())
   .with_component(ColliderComponent::builder()
       .shape(SharedShape::ball(1.0))  // Match mesh size
       .mass(10.0)  // Don't forget mass!
       .build())

2. Check physics timestep in config.ini:

   [physics]
   timestep = 0.016667  # 60 FPS

3. Verify collider sizes: Make sure collider shapes match visual meshes reasonably well.

Objects Won't Move

Problem: Dynamic objects don't respond to forces.

Solutions:

1. Check body type:

   RigidBodyComponent::builder()
       .body_type(RigidBodyType::Dynamic)  // Not Fixed or Kinematic
       .build()

2. Verify mass:

   ColliderComponent::builder()
       .mass(10.0)  // Must be > 0 for dynamic objects
       .build()

3. Check if gravity is enabled:

   [physics]
   gravity = -9.81  # Negative for downward

Jittery Physics

Problem: Objects shake or vibrate.

Solutions:

1. Add damping:

   RigidBodyComponent::builder()
       .body_type(RigidBodyType::Dynamic)
       .linear_damping(0.5)   // Reduces movement
       .angular_damping(0.5)  // Reduces rotation
       .build()

2. Adjust collision properties:

   ColliderComponent::builder()
       .friction(0.5)      // Surface friction
       .restitution(0.3)   // Bounciness (lower = less bounce)
       .build()

3. Use continuous collision detection: For fast-moving objects, enable CCD (check engine docs).

Resource Loading Issues

Model Not Rendering

Problem: Mesh doesn't appear even though code seems correct.

Solutions:

1. Verify file exists: Check that res/models/YourModel.obj exists.

2. Check model format:

   • Must be OBJ format
   • Should have normals and UVs
   • No extreme polygon counts

3. Verify resource handle:

   let mesh = engine.add_resource(Mesh::new("Test", "models/Test.obj".into()))?;
   // Make sure this doesn't error!

4. Check material setup: Objects need both mesh AND material to render.

Texture Not Loading

Problem: Model shows up but texture is missing or wrong.

Solutions:

1. Check texture path:

   Texture::new(
       "MyTexture",
       TextureType::Color,
       ResourceLoadType::Path("textures/MyTexture.png".into())  // Check this path!
   )

2. Verify texture format:

   • Supported: PNG, JPEG, BMP, TGA
   • RGB or RGBA
   • Power-of-2 dimensions recommended (512x512, 1024x1024, etc.)

3. Check material binding:

   Material::builder("MyMaterial")
       .texture("Color", texture_handle)?  // Make sure this is correct
       .build()

Audio Not Playing

Problem: No sound or audio source not working.

Solutions:

1. Check audio listener:

   // Must have one AudioListenerComponent in scene
   engine.build_entity(scene)
       .with_component(CameraComponent::default())
       .with_component(AudioListenerComponent::builder()
           .enabled(true)
           .build())
       .build();

2. Verify audio source:

   AudioSourceComponent::builder()
       .audio_clip(&clip_handle)
       .volume(1.0)      // 0.0 = silent, 1.0 = full volume
       .looping(true)    // For continuous sounds
       .play_on_start(true)  // Start immediately
       .build()

3. Check file format:

   • Supported: WAV, OGG, MP3
   • Not corrupted
   • Reasonable file size

4. Verify Windows audio: Make sure your system volume is up and not muted.

Networking Issues

Cannot Connect to Server

Problem: Client can't connect to server.

Solutions:

1. Check server address:

   let server_addr = "127.0.0.1:5000";  // Correct IP and port?

2. Verify server is running: Make sure the server application started successfully.

3. Check firewall: Windows Firewall might block the connection. Add exception if needed.

4. Enable net feature:

   [dependencies]
   pill_engine = { path = "../Pill-Engine/engine/pill_engine", features = ["net"] }

5. Use conditional compilation:

   #[cfg(feature = "net")]
   {
       // Networking code here
   }

Entity Sync Issues

Problem: Entities don't synchronize properly between clients.

Solutions:

1. Verify NetworkStateComponent:

   NetworkStateComponent {
       net_entity_id: unique_id,  // Must be unique per entity!
       owner_id: client_id,
       state: NetEntityState::Spawn,
       transform: Some(transform.clone()),
   }

2. Check update frequency: Balance between bandwidth and responsiveness.

3. Add networking system:

   engine.add_system("NetworkingClient", pill_engine::networking_system_client)?;

Hot Reloading Issues

Changes Not Reloading

Problem: Code changes don't reflect in running game.

Solutions:

1. Rebuild the library:

   cargo build

   Hot-reload only works if you rebuild!

2. Check file watcher: Make sure pill_standalone is monitoring the correct DLL.

3. Verify DLL output:

   cargo build --message-format=short

   Check that the DLL is actually being updated.

4. Try restarting: Sometimes a full restart is needed after major changes.

Editor / IDE Issues

rust-analyzer Errors

Problem: VS Code shows errors that don't exist or won't go away.

Solutions:

1. Reload window:

   • Press Ctrl+Shift+P
   • Type "Reload Window"
   • Press Enter

2. Restart rust-analyzer:

   • Press Ctrl+Shift+P
   • Type "rust-analyzer: Restart server"
   • Press Enter

3. Check Cargo.toml: Make sure all dependencies are valid.

4. Clean and rebuild:

   cargo clean
   cargo build

Slow Autocomplete

Problem: IDE is slow or unresponsive.

Solutions:

1. Disable unnecessary features: In settings.json:

   {
     "rust-analyzer.checkOnSave.command": "clippy",
     "rust-analyzer.cargo.loadOutDirsFromCheck": false
   }

2. Increase memory limit: Close other applications to free up RAM.

3. Exclude target directories:

   {
     "files.watcherExclude": {
       "**/target/**": true
     }
   }

Getting More Help

If your issue isn't covered here:

1. Check example projects: See how they handle similar situations
2. Enable debug logging: Add println!() statements to understand flow
3. Read error messages carefully: They often point to the exact problem
4. Search GitHub issues: Someone might have had the same problem
5. Create a minimal reproduction: Simplify your code to isolate the issue

Creating a Bug Report

When reporting issues, include:

• Rust version: rustc --version
• OS and version: Windows 10/11, etc.
• Minimal code example: Smallest code that reproduces the issue
• Error messages: Full error text with backtrace
• What you expected: What should happen
• What actually happened: What went wrong

Useful Debug Commands

# Check Rust installation
rustc --version
cargo --version

# Verbose build output
cargo build --verbose

# Run with backtrace
$env:RUST_BACKTRACE=1; cargo run

# Check dependencies
cargo tree

# Clean everything
cargo clean
Remove-Item -Recurse -Force target/

Common Error Messages

"Cannot find crate for pill_engine"

Fix: Check the path in Cargo.toml points to the correct location.

"No such file or directory (os error 2)"

Fix: Resource file doesn't exist. Check the path and filename.

"Thread 'main' panicked at..."

Fix: Check the line number and error message. Often indicates:

• Missing component registration
• Invalid handle use
• Resource not found

"Borrow checker error"

Fix: You're trying to borrow engine mutably multiple times. Restructure your code to release borrows earlier.

Performance Benchmarks

Expected performance on modern hardware:

• 1000 static entities: 60+ FPS
• 100 dynamic physics objects: 60 FPS
• Simple game: 60-144 FPS
• Complex scene: 30-60 FPS

If you're below these, check the performance optimization section in Next Steps.

---

Still stuck? Feel free to open an issue on GitHub with details about your problem!