Adding Zernikalos to Your Project

Configuration

After the basic setup, you'll need to publish the library locally:

./gradlew publishToMavenLocal

Then add the dependency to your app's build.gradle.kts file:

dependencies {
    implementation("dev.zernikalos:zernikalos:0.0.1")
}

If you haven't already, make sure you have mavenLocal() in your project's repositories:

repositories {
    mavenLocal()
    // ... other repositories
}

We recommend using CocoaPods for integration:

Add the following to your Podfile:

pod 'Zernikalos', :path => 'path/to/zernikalos/podspec'

Run pod install:

pod install

Import the engine

Before integrating Zernikalos, ensure you have:

An Android project set up
OpenGL ES 3.0 or higher declared in your AndroidManifest.xml:

<uses-feature android:glEsVersion="0x00030000" android:required="true" />

A GLSurfaceView in your layout - This will be the canvas where Zernikalos renders your scene. (Android GLSurfaceView documentation)

Add a GLSurfaceView to your layout file:

<android.opengl.GLSurfaceView
    android:id="@+id/render_surface"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Initialize Zernikalos in your Activity's onCreate method:

val zernikalos = Zernikalos()
val renderSurface = findViewById<GLSurfaceView>(R.id.render_surface)

zernikalos.initialize(renderSurface, object : ZSceneStateHandler {
    // ZSceneStateHandler implementation will be covered in the next section
})

iOS documentation coming soon...

Implementing the ZSceneStateHandler

The ZSceneStateHandler interface is crucial for managing the lifecycle of your Zernikalos scene. Here's a basic implementation:

zernikalos.initialize(renderSurface, object : ZSceneStateHandler {
    private var scene: ZScene? = null
    private var camera: ZCamera? = null

    override fun onReady(context: ZContext, done: () -> Unit) {
        scope.launch {
            // Create and set up your scene
            scene = ZScene()

            // Load your 3D assets
            val zko = loadResources()

            // Add objects to the scene
            scene?.addChild(zko.root)

            // Set the scene in the context
            context.scene = scene

            // Signal completion
            done()
        }
    }

    override fun onResize(context: ZContext, width: Int, height: Int, done: () -> Unit) {
        done()
    }

    override fun onRender(context: ZContext, done: () -> Unit) {
        // Your per-frame updates here
        done()
    }
})

Loading Resources

The most common first step is loading your 3D assets from a .zko file. Here's how to do it:

suspend fun loadResources(): ZKo = coroutineScope {
    val data = applicationContext.assets.open("your_model.zko")
    return@coroutineScope loadFromProto(data.readBytes())
}

Key Components

Scene Setup: In onReady, you create your scene and load resources
Resource Loading: Use .zko resource files containing your 3D models
Scene Context: The ZContext provides access to the current scene and rendering state
Lifecycle Methods:
- onReady: Called when the engine is ready to start rendering
- onResize: Called when the surface size changes
- onRender: Called every frame for continuous updates