zCube Core Engine API (z3engine extension )

z3engine API (zCube core extension )

This z3 core extension includes the zCube general API and IPC functions. This is a small part of the features present in the zCube runtime application (read the doc online for more info on zCube Runtime). This extension can be used by application with embedded Lua or with Lua or luaJIT runtime.

Functions

init()
mainmodule()
getinfo()
sleep()
iswindowexists()
openusersharedmemdata()
getusersharedmemdata()

Initialization

init() initialise the module

To guarantee the compatibility of your script with the zCube Runtime App it’s recommended to instantiate the z3engine extension with z3e name.
With the line below your scripts will run on zCube runtime or Lua / LuaJIT runtime with z3 core engine extension.

if z3e == nil then local z3e = require(“z3engine”) end

mainmodule() is used to register the first zCube device extension
both functions are required to initialize zCube core engine (see the example below)
you only need to register the first one even if you load more than one zCube device extension

Example Initialize With SLIPRO device extension (z3slipro)

-- load extension and create the z3e instance
-- if not already created by zCube Runtime
if z3e == nil then local z3e = require(“z3engine”) end

-- load device extension and create the slipro instance
local slipro = require(“z3slipro”)
-- init core
z3e.init()
--  init slipro device
if slipro.init() then
	-- register main module
	z3e.mainmodule(slipro.getmodule())

	-- your script here
	
	-- end of script
	slipro.terminate()
end

getinfo(selector) function

get device information and capabilities

-- SELECTOR STRING
-- ---------------------------------------------------------------------------
"version" 
-- return version as string
-- example:
	local z3dll_vers = z3e.getinfo("version")

"name" 
-- return name of extension as string
-- example:
	local device_name = z3e.getinfo("name")

"engine" 
-- return "standard" for the core extension as string
-- example:
	local device_name = z3e.getinfo("engine")

"ticks" 
-- return number of ticks elapsed since PC startup
-- example:
-- if z3e.getinfo("ticks") > old_tick then print("time elapsed!" end

"is running" 
-- return 1 if the module is still valid and running
-- example:
	while z3e.getinfo("is_running") do
		-- your script
	end

sleep(ms) function

The time interval for which execution is to be suspended, in milliseconds.

-- wait for 100 milliseconds
z3e.sleep(100)

openurl(string file/folder path/url) function

Use the shell API to open folder, file or url with default application.

if filepath ~= nil and filepath ~= '' then openurl(filepath) end

local url = "https://www.eksimracing.org"
openurl(url)

boolean iswindowexists(window_name_string[, boolean_strict]) function

Check if the window exists,
window_name_string is a string the name of the window
boolean_strict is a boolean, this parameter is optional, pass true for an exact match
return true if exists or false

local isRunning = true
while isRunning do
  if z3e.iswindowexists("Assetto Corsa", true) == false then
   -- time to quit
    isRunning=false
  end
end

local isRunning = true
while isRunning do
  if z3e.iswindowexists("GTR2") == false then
   -- time to quit
    isRunning=false
  end
end

boolean openusersharedmemdata(sharedmem_name, buffer size, ref_index) function

open an existing global shared memory with its exact name (string) and size of the buffer (integer)
a reference index (from 1 to 10) is passed in param 3
To get the pointer of the shared memory buffer.pass the reference index to the function getusersharedmemdata(ref_index)
This function is very useful to get the telemetry data from games like Simbin, Sector 3, AC, ACC,…and many others

Return

Return true if it opens the shared memory successfully

ffi extension is included with all zCube runtime pkgs and is recommended for playing with game structure data, see the example below.

local sz = ffi.sizeof(“struct simbinsharedmem_t”)
if z3e.openusersharedmemdata(“$gtr2$”, sz, 1) then
	print(“server session starts”)
end

lightuserdata getusersharedmemdata(ref_index) function

get the pointer of the shared mem buffer opened by opensharedmemdata()
pass the reference index (from 1 to 10)

Return

a lightuserdata object or nil

use ffi to cast the returned lightuserdata to the game structure data, see the example below.

local gtr2data = z3e.getusersharedmemdata(1)
if gtr2data ~= nil then
  -- cast pointer data to gtr2 struct using ffi
  local data = ffi.cast("simbinsharedmem_t*", gtr2data)
  local gear = data.gear
end

Minimal Script

-- minimal script for zCube device extension

if z3e == nil then local z3e = require(“z3engine”) end
local dev = require("your-extension-here") -- replace with the corresponding zCube extension

-- init core
z3e.init()

-- init device
if dev.init() then
	 -- register main module
	 z3e.mainmodule(dev.getmodule())

	 -- your custom script here

	 dev.terminate()
end