KZX Engine Documentation

               Welcome to the official documentation for the KZX Engine.

                                         All neccessary information will be explained here within this documentation site.




Installation

Follow the steps of the KZX setup:

  1. Dowload the KZX Engine setup. You will need to click the dowloaded file wich you can dowload on the homepage. When you have pressed the dowloaded setup, you will have to authorize the installation with adminitrative priviledges by accepting the "YES" button.
  2. Below we shall instruct you on how you can go through all the following steps from the installer:
      • 1. Select your setup language and press on, "OK".
      • 2. Accept the license agreement, and press on, "Next".
      • 3. Some information will display, then press on, "Next".
      • 4. Select if you want to have an shortcut icon on your desktop and then press on, "Next".
      • 5. Now you will see the Installation tab and click on, "Install".
      • 6. The installation is now completed you will be able to start the KZX Engine optionally after pressing finish, now click on, "Finish".
  3. Congratulations, you are now able to startup the KZX Engine project hub and start to work on the KZX Engine!

Project Hub

KZX Engine has an project hub at the beginning of starting the engine. You can use the directories where you want to store your .kzxproject a .kzxproject is an exclusive extension to the KZX Engine for the engine to identify and load its own project file and the related source files. The project hub gives your full control over your projects if you want to either make a new one or remove/open existing ones. This allows for easier use to use your projects.


The image below is an old reference:


Editor Controls

These are all the necessary key inputs & combines for the KZX Engine at the moment.

Action Input
Rotate the camera
Zoom in/out
Move camera Forward +
Move camera Backward +
Move camera left +
Move camera Right +
Move camera Up +
Move camera Down +
Orbit Around Selected +
Move to selection
Move to selected (From Top)
Move to selected (from Bottom)
Move to selected (From Left)
Move to selected (from Right)
Move to selected (from Front)
Move to selected (From Back)
Delete selected
Switch Selected Gizmo Transform
Switch Selected Gizmo Rotation
Switch Selected Gizmo Scaling

KZX Engine References

Every extension and related element you should know for using the engine will be displayed here. Here are some terms that you'll encounter while using or reading about the KZX Engine.

Term Definition
Window As the KZX Engine is fully modulable, it is possible to undock or move around parts of the editor. We will call these parts windows.
Menu Bar Top bar of your main window, containing menus such as File, Build and Window etc.
Actor Any entity with components in the KZX Engine is called an actor. Actors are part of the root in a scene.
Scene A collection of actors. It can be serialized to a XML format (Aka, .kzxscene format) to be loaded another time by the editor or the game.
Mesh Set of vertices and indices. You can't manipulate meshes directly from the editor.
Model Collection of meshes. Each model can be composed of multiple meshes. They directly represent a model file (fbx, obj Etc.). They can be spawned into a scene.
Material Defining the visual look of any object using it. A material can be changed with certain settings to define its color or texture.
Asset Metadata Set of settings that will influence the way an asset should be loaded or can be loaded.
Gizmo A gizmo is a set of 3D arrows and circles, those are draggable, used to manipulate an actor in the Scene View within the editor.
Scene Root We use this term for all the stuff in a scene, the ROOT is part of the Hierachy Window all the placed actors will be placed underneath it.
Extension Definition
.kzxproject A .kzxproject is an file for the KZX Engine to load your created project, this file is to let the engine identify the project in your project source path.
.kzxscene The .kzxscene is an XML packaged file with all the saved root files in-editor for the KZX Engine to load/save your scene. This file is to let the engine identify your scene within the editor.
.kzxmat We use the .kzxmat as our material extension this is for loading and saving your material files within the editor, this is so that the editor can load your materials on your models.
.fbx & .obj the .obj and the .fbx is an model extension we use for loading in a 3D model objects to the engine root.
.lua Lua programming language extension is using the .lua file extension it basically saves your script in the file.

The Basics

The basics for the KZX Engine. This section is to actually use the editor and to learn from it.

Scene Creation

Creating your scene, follow this topic to learn about creating your first scene.

Making a new scene

You can make a new scene by going to File > New Scene" (Or use Ctrl - N)





Saving your scene

You can both save your created scene by going to File > Save Scene (Or use Ctrl-S). When you made a new un-named scene you must first have an directory for it to actually this must be in the project assets directory files. Second you can also do "Save As" wich can be found at File > Save Scene As (or use Ctrl-Shift-S, wich can copy your existing scene wich you can use for back-ups or just for copying it.


Placing Objects

Documentation and examples for displaying inline and multiline blocks of code

Creating Scene Actors

You can create actors in the KZX Engine by using your "right mouse button" On the Root Library in the Hierachy Window, you will see a popup saying Create when you click on it you will get options like actors, lights etc.




Adding external 3D Models

You can add both .obj or .fbx to the KZX Engine. For adding an custom 3D model you must first import it by going to the Assets folder in the Assets Browser Window, simply paste your 3D file in a folder there you are good to go to put your model in the scene by dragging and dropping. The 3D Model will be automatically be made an Actor in the Root Library.




Using Materials

In this topic we are using and making our material pipeline systems.

KZX Engine uses an advanced material editor this supports both normal material shaders or PBR material shaders. Or even your custom shaders.

Creating Materials

So when you are in the editor you can go to the assets browser window, you can now right click then go to Create.. > Material > Standard PBR (Or any other material type you want) And then give your PBR material a name.



Now our PBR material is made, you can now right click on your created PBR material and click on "Edit".


If you have clicked the "Edit" button you will now see the Material Editor Window. The window shows you all the necessary shader functions for the material to be made. As example i will make an wooden type color without textures, you can choose for yourself if you need textures. The material editor works the same as the Unity 3D Engine, the textures have to be dragged/dropped in the Mapping boxes.



The KZX Engine doesnt work without material saving, so be sure to save your material to the file. This can be found in the upper area of the Material Editor Window.



Congratulations you have created your first material, ofcourse you can change your material in anyway you like, this was just a simple demonstration.


Additional Features

In this topic we are going to show extra features we have added to the KZX Engine wich we havent shown in the Documentation.

Using Lighting.

So you can add light in 5 diffirent ways to the KZX Engine.

Type Function
Directional Lighting The directional lighting is used for sun based lighting that is coming from one direction, this is the most commonly known lighting based rendering.
Point Light A point light is an actor light source that is rendered in a way for pointing in all directions.
Spot Light The Spot Light is an actor for pointing towards one direction.
Ambient Lighting (Cubical & Spherical) An ambient light is covering a section wich can both be in a Cubical Form or in a Spherical Form. that is giving off an ambient light, this light is basically rendering the lighting in a scene similar to a baked map.

Here are all of the light actors in action

Frustrum Culling

So yes, you can add Frustum Culling to the KZX Engine. For those who dont know Frustum Culling, it basically is a form of camera rendering, all the objects outside the camera's field of view will disapear for optimal performance. To visualize frustrum culling in your project you must first enable both frustrum options in your camera and then use the debug option for them which is located under the settings menu bar you can also follow the showcase video bellow.

Using Physical Based Collisions

KZX Engine uses Physics based collision system for the physical based actors, these Collisions can enable or disable kinematics and gravity and can also be used for event based triggers. These settings can be fully adjusted

Using Kinematics

Kinematics basically make a physical actor gravity proof, By enabling your kinematic settings you can have static walkable areas or have other actors to fall or be placed on that kinematic enabled actor.

KZX Engine uses Physics based collision system for the physical based actors, these Collisions can enable or disable kinematics and gravity and can also be used for event based triggers. These settings can be fully adjusted

Using Gravity

Gravity is a simple yet important system within our game engine. It basically manipulates the whole scene with diffirent gravity functions.






More Features Soon...


Making Lua scripts.

In this section we will explain the whole usage of the lua programming language for the KZX Engine, below are some example scripts.

Using the console

To make messages appear in the editor console you can use the following lua script input sample for in the editor.

 local helloworld =
{
}

function helloworld:OnStart()
  
  Debug.Log(tostring("Hello World :D"))

end

return helloworld

Console Output:

Up/Down

The console can display diffirent type of messages in regard to your use for them like text or even displaying mathmathical calculations in runtime.

Move Up/Down

This is an simple lua script to move any object within KZX Engine move up and down.

Up/Down


-- Holds data that are shared between functions of this usertype
local MoveUpDown =
{
    elapsed = 0
}

-- Called when the scene starts
function MoveUpDown:OnStart()
end

-- Called every frame (The passed deltaTime holds the time elapsed between the current and previous frame in seconds)
function MoveUpDown:OnUpdate(deltaTime)
    -- Here, elapsed is incremented to sum the elapsed time since start
    self.elapsed = self.elapsed + deltaTime

    -- Stores the transform component instance into a variable
    transform = self.owner:GetTransform()

    -- Invoke SetPosition function with `:` to send the transform instance as first parameter to this function
    -- `transform:SetPosition(...)` is equivalent to `transform.SetPosition(transform, ...)`
    transform:SetPosition(Vector3.new(0, math.sin(self.elapsed), 0))

end

-- Returns the usertype so the engine has a reference to it
return MoveUpDown

This script purely was to demonstrate the code in action including some explanation.

Some more in depth explanation:

The local (YourScriptName) = {...} should contains any variable that your script wants to share between the functions. The ():OnStart() function is called once the scene with your script (AKA behaviour) is loaded, and the ():OnUpdate(deltaTime) is called every frame. There are multiple engine functions that you can use in your scripts to create complex gameplay logic, Please, check below for examples.

Rotation

This is an simple script to rotate any object in its own axis, within KZX Engine.

Rotate



local Rotator =
{
    eulerAngles = Vector3.new(0, 0, 0)
}

function Rotator:OnUpdate(deltaTime)
    self.eulerAngles.y = self.eulerAngles.y + 90 * deltaTime
    self.owner:GetTransform():SetRotation(Quaternion.new(self.eulerAngles))
end

function Rotator:OnAwake()
    self.eulerAngles = self.owner:GetTransform():GetRotation():EulerAngles()
end

return Rotator

This rotation script was to show the user that you can make any simple object rotate by using this script.

Advanced FPS Controller

This is a script that allows you to have an advanced fps controller. This script understanding is for some more experienced programmers. if you are not familiar with Lua it can be hard to understand.

Rotate



local FPSController =
{
    walkSpeed           = 3,
    runSpeed            = 6,
    mouseSensitivity    = 0.05,
    mouseLook           = Vector2.new(180, 0),
    previousMouse       = Vector2.new(0, 0),
    firstMouse          = true,
    body                = nil,
    mouseLocked         = true,
    isGrounded          = false,
    defaultRotation     = nil
}

function FPSController:OnAwake()
    self.body = self.owner:GetParent()
    self.defaultRotation = self.body:GetTransform():GetRotation()
end

function FPSController:OnStart()
    if self.mouseLocked then
        Inputs.LockMouse()
    end
end


function FPSController:OnUpdate(deltaTime)
    -- Toggle mouse lock with Left ALT key (Optionally Can be removed)

    if Inputs.GetKeyDown(Key.LEFT_ALT) then
        self.mouseLocked = not self.mouseLocked
        self.firstMouse = true
        if self.mouseLocked then
            Inputs.LockMouse()
        else
            Inputs.UnlockMouse()
        end
    end

    -- Handle mouse and keyboard only if mouse is locked 
    if self.mouseLocked then
        self:HandleMovement(deltaTime)
        self:HandleRotation(deltaTime)
    end
    self:CheckGround()
end

function FPSController:HandleMovement(deltaTime)
    velocity = Vector3.new(0, 0, 0)

    forward = self.body:GetTransform():GetForward()
    right   = self.body:GetTransform():GetRight()

    if Inputs.GetKey(Key.LEFT_SHIFT) then speed = self.runSpeed else speed = self.walkSpeed end
    if Inputs.GetKey(Key.A) then velocity = velocity + right end
    if Inputs.GetKey(Key.D) then velocity = velocity - right end
    if Inputs.GetKey(Key.W) then velocity = velocity + forward end
    if Inputs.GetKey(Key.S) then velocity = velocity - forward end

    if Inputs.GetKeyDown(Key.SPACE) and self.isGrounded then
        physicalCapsule = self.body:GetPhysicalCapsule()
        physicalCapsule:AddImpulse(Vector3.new(0, 4, 0))
    end

    velocity = velocity * speed

    previousPosition    = self.body:GetTransform():GetPosition()
    newPosition         = previousPosition + velocity

    --self.body:GetTransform():SetPosition(newPosition)
    velocity.y =  self.body:GetPhysicalCapsule():GetLinearVelocity().y
    self.body:GetPhysicalCapsule():SetLinearVelocity(velocity)
end

function FPSController:HandleRotation(deltaTime)
    mousePosition = Inputs.GetMousePos()
    
    if self.firstMouse == true then
        self.previousMouse = mousePosition
        self.firstMouse = false
    end
    
    mouseOffset = Vector2.new(0, 0)
    mouseOffset.x = mousePosition.x - self.previousMouse.x
    mouseOffset.y = self.previousMouse.y - mousePosition.y

    self.previousMouse = mousePosition

    mouseOffset = mouseOffset * self.mouseSensitivity

    if Inputs.GetKey(Key.G) then
        Debug.Log(tostring(mousePosition.y))
    end

    self.mouseLook = self.mouseLook + mouseOffset;

    -- Clamp x and y
    if self.mouseLook.y > 89    then self.mouseLook.y = 89  end
    if self.mouseLook.y < -89   then self.mouseLook.y = -89 end

    self.owner:GetTransform():SetRotation(Quaternion.new(Vector3.new(-self.mouseLook.y, 0, 0)))
    self.body:GetTransform():SetRotation(self.defaultRotation * Quaternion.new(Vector3.new(0, 180 - self.mouseLook.x, 0)))
end

function FPSController:CheckGround()

    Hit = Physics.Raycast(self.body:GetTransform():GetPosition() - Vector3.new(0, 0.75, 0), Vector3.new(0, -1, 0), 0.75)
    
    if Hit ~= nil then
        self.isGrounded = true
    else
        self.isGrounded = false
    end
end

return FPSController

This script was to demonstrate the possibilities with the KZX engine when you combine efficient Lua scripting.

Function Behaviours

The KZX Engine has a variety of function behaviours that you can use for the scripts, you can see all the behaviours below.

Name Description
()OnAwake Called when the scene start right before OnStart
()OnStart Called when the scene start right after OnAwake
()OnEnable Called when the behaviour gets enabled (owner SetActive set to true)
()OnDestroy Called when the behaviour gets destroyed
()OnUpdate Called every frame
()OnFixedUpdate Called every physics frame
()OnLateUpdate Called every frame after OnUpdate
()OnCollisionEnter Called when the owner of this behaviour enter in collision with another physical object
()OnCollisionStay Called when the owner of this behaviour is in collision with another physical object
()OnCollisionExit Called when the owner of this behaviour exit from collision with another physical object
()OnTriggerEnter Called when the owner of this behaviour enter in trigger with another physical object
()OnTriggerStay Called when the owner of this behaviour is in trigger with another physical object
()OnTriggerExit Called when the owner of this behaviour exit from trigger with another physical object

Applying the script

After making your script you want to make sure to apply the script to a desireable object or system by dragging and dropping this is important to know because there is no other way to apply your script.


Project Settings & Game Building

Final step on finishing your game is to setup your project settings and to build it.,

Project Settings

This image shows you all the settings that you have within the Project Settings tab, you can customize as much as you like

Be sure to actually press "Apply" for the settings to work, then after that your game is ready for build & shipping.

Name Description
Physics This setting allows you to manipulate gravity settings within the engine.
Build This feature can be enabled or disabled, this basically makes an "Debugged" version of the packaged game.
Windowed The features in this catagory are for how your game is named and how big the screen resolution is and if your want it to start on fullscreen.
Rendering The features in this catagory are for how your game is going to look like visually.
Scene Management This feature basically makes you start your created scene.

Building your game.

You can now finally build your game either in shipping mode or in development mode, you can go to the very top bar and select "Build" within the sub navbar you will see "Build Game" just click that and you are ready to go. If you were to select the "Build Game and run" the game will automatically start after building. Also be sure to check the logs for errors.

The console should look like this with a succesfull build, if you get any errors then the problem would be that the engine wasnt succesfully installed by missing files or that you have a duplicated config file of the "Non builded-build" wich can be found in the Engine directories.


Scripting API

This is our full list of every lua binded component within our engine that can be manipulated by using a lua script.


Globals (WIP)

Every Global Component for lua scripting.

Console

Lua scriptable debug components for the KZX console.

Name Description Development Status
Log Default color white console log Success
LogInfo Info color blue console log Need Fixing
LogWarning Warning color orange console log Success
LogError Error color Red console log Success

Scene Components

Lua scriptable scene components.

Name Description Development Status
FindActorByName WIP Success
FindActorByTag WIP Success
FindActorsByName WIP Success
FindActorsByTag WIP Success
CreateActor WIP Success

Transform (WIP)

Transform Components.

Name Description
SetPosition Alias for SetLocalPosition
SetRotation Alias for SetLocalRotation
SetScale Alias for SetLocalScale
SetLocalPosition Sets the position of the transform in the local space
SetLocalRotation Sets the rotation of the transform in the local space
SetLocalScale Sets the scale of the transform in the local space
GetPosition WIP
GetRotation WIP
GetScale WIP
GetLocalPosition WIP
GetLocalRotation WIP
GetLocalScale WIP
GetWorldPosition WIP
GetWorldRotation WIP
GetWorldScale WIP
GetForward WIP
GetUp WIP
GetRight WIP
GetLocalForward WIP
GetLocalUp WIP
GetLocalRight WIP
GetWorldForward WIP
GetWorldUp WIP
GetWorldRight WIP

FAQ

Here you can see all the frequently asked questions.

Yes! You can sell your game without any fees or extra payments!
No, you are not authorized to re-sell or commercialize our 3D Game Engine in anyway.
Yes, our purpose was to make the KZX Engine for students and for you to learn from it.
No, currently not. The KZX Engine is an freeware application at the moment! However this might change in the future.
Basically you can go 2 ways with this, either use samples on our forum and learn from those or go to the official lua.org website and see tutorials about the lua programming language!
Yes, you can modify the engine to a certain extend please check our software license.

Sources & Libraries

Press:

Official Documents:

  • KZX Engine Software License Agreement - View
  • Terms Of Use - WIP
  • Privacy Policy - WIP

Libraries & Thirdparties:


Changelog

See what's new added, changed, fixed, improved or updated in the latest versions.

Version 4.0.2 (Public Stable Release)

(21st April 2022)

  • Public Build
  • This version is soley for updating and enhancing the engine on flaws and some extra functions.

  • Future
  • - Real-time Texture Painting Tool

  • ADDED
  • - Solved certain dependancies that can cause unexpected crashes.

    - Added C# script option, (Early Feature)

    - Added .dae model support, (Early Feature)

    - Improved the engine profiler for the best performance.

  • UNSOLVED
  • - Code Signing Certificate

    - Drag/Drop assets in engine to folders, same for scripts (this causes crashes right now)

    - Post Processing Features

    - Terrain System

    - Fur System

    - Real-time Texture Painting Tool

Version 4.0.1 (First Public Stable Release)

(6th January 2022)

  • Public Build
  • Finally, we released our KZX Engine to the public for dowloading. This is our first major PUBLIC and stable release.

  • Future
  • KZX Engine will have more features including terrain and Fur, these features will come very late on since its not our priority at the moment.

  • ADDED
  • - Added Frustrum Culling for Geometrics and lighting.

    - Added Terrain Windows & tabs.

    - Added Fur/Hair Windows & tabs.

    - Added Asset Preview Window.

    - Added New Menu Bar section, "Tools(WIP)"

    - Added profiler system

    - Fixed Console systems

    - Made Preparations for Terrain & Fur/Hair Systems for next updates.

    - Fixed Material Functionality Bugs.

    - Solved Major Bugs & Managed to fix alot of further issues.

    - Updated & Enhanced the whole scripting functions with lua.

  • UNSOLVED
  • - More editor keybindings, These will be added later

    - More features for scripting.


All pre/closed versions, v1.0 till v4.0.0 (Closed Releases)

(2014 - 2021)

  • Initial Build
  • The official closed releases of the KZX Engine these builds were intended for internal/private uses and were not shared to the public. These updates contained alot of features and major fixes. During the development of these versions all of these created features etc are seen back in the 4.0.1 & 4.0.2 public releases. For better information on all the updates you can check our KZX Engine trello board.