Understanding ShiVa3D Architecture

Editor, Engine, and Deployment Toolchain

ShiVa3D projects are developed using the ShiVa Editor, compiled into engine-compatible formats, and deployed using ShiVa Authoring Tool (SAT). A disconnect between editor configuration and SAT export often causes runtime or build issues.

Lua Scripting and Plugin System

The scripting environment is Lua-based, but developers can extend functionality using C++/C# plugins. Errors can occur during runtime if plugin APIs are misaligned or dependencies are missing on the target platform.

Common ShiVa3D Issues in Production

1. Engine Crashes on Mobile Platforms

Mobile builds often crash due to improper memory allocation, unsupported shaders, or incorrect plugin architecture. These errors are hard to detect until deployed on physical devices.

2. Plugin DLL/so/Dylib Not Loaded

External plugins might not be correctly registered in the SAT or may miss platform-specific binary versions. This results in null object references or function call failures.

3. Lua Runtime Errors with Ambiguous Messages

Incorrect API usage, deprecated calls, or malformed parameter tables can cause the Lua interpreter to throw cryptic errors without detailed stack traces.

4. Poor Rendering Performance

High poly models, unoptimized materials, and excessive draw calls lead to FPS drops. The engine lacks built-in GPU profilers, so developers must use platform-specific tools.

5. Asset Import Fails or Breaks on Export

Meshes or animations from external tools (e.g., Blender, Maya) may not export cleanly due to unsupported formats, missing bone structures, or incorrect file paths in SAT.

Diagnostics and Debugging Techniques

Use Device-Specific Logs

• On Android, use adb logcat to capture runtime errors and plugin load failures.
• On iOS, review Xcode logs and enable symbolicated crash dumps.

Enable Verbose Export in SAT

• Use SAT's advanced options to enable export logs.
• Verify the presence and structure of plugin folders, textures, and media files in the exported package.

Debug Lua Scripts

• Use application.log to capture console prints and errors.
• Implement defensive coding practices with pcall to capture unexpected runtime exceptions.

Profile Rendering and Memory

• Use platform GPU profilers like Adreno Profiler (Android) or Xcode Instruments (iOS).
• Reduce overdraw, batch static geometry, and compress textures where possible.

Validate Plugin Configuration

• Check plugin.xml and ensure correct registration for all platforms.
• Verify C++ plugin symbols are correctly exported and compiled using platform-specific compilers.

Step-by-Step Fixes

1. Fix Mobile Engine Crashes

• Reduce texture size and mesh complexity in initial scenes.
• Test with simplified shaders and disable complex particle effects to isolate the crash.

2. Resolve Plugin Load Failures

• Ensure the Plugins folder includes platform-specific binaries (e.g., .so for Android, .dylib for iOS).
• Update plugin.xml to declare dependencies explicitly.

3. Debug Lua Runtime Errors

local success, err = pcall(function()
  this:myCustomFunction(nil)
end)
if not success then
  log.message("Lua Error: " .. err)
end

4. Improve Performance on Target Devices

• Use baked lighting instead of real-time lighting for static scenes.
• Minimize dynamic shadows and limit alpha-blended surfaces.

5. Correct Asset Import Problems

• Use FBX 2013 or earlier formats for compatibility.
• Clean up rigs and bake animations before export. Use consistent naming for assets.

Best Practices

• Keep Lua code modular and maintain strict typing in function arguments.
• Automate builds and test exports on all target platforms regularly.
• Use lightweight plugins and strip unnecessary symbols for mobile deployment.
• Organize project folders clearly to simplify asset referencing and reduce SAT export bugs.
• Document plugin interfaces and maintain backward compatibility during updates.

Conclusion

ShiVa3D is a versatile engine, but building stable and high-performance games with it requires an understanding of its scripting, export, and deployment intricacies. From plugin loading errors to rendering slowdowns, issues often arise due to configuration mismatches or overlooked engine constraints. By employing structured debugging, optimizing assets, and following clear development workflows, developers can unlock ShiVa3D's potential across platforms while minimizing downtime and production risks.

FAQs

1. Why does my ShiVa3D app crash on Android after deployment?

Check for missing native libraries, unsupported shaders, or excessive memory usage. Use adb logcat to trace the issue.

2. How do I debug Lua scripts in ShiVa3D?

Use application.log for console output. Wrap critical function calls in pcall to prevent hard crashes and capture error messages.

3. Why isn't my plugin being loaded?

Ensure platform-specific binaries are present and plugin.xml correctly references the plugin. Verify symbol exports during compilation.

4. What causes performance issues on mobile devices?

Likely culprits include high poly models, large textures, dynamic lights, or too many draw calls. Use platform-specific profilers to isolate the cause.

5. How do I fix asset import errors from Blender?

Export using FBX 2013, bake animations, and ensure the skeleton structure is simplified. Avoid using unsupported constraints or modifiers.