Coppercube Extended functions API

Run "Coppercube Extended functions API"(action_ccbAPI) at the start of your game to guarantee functions are available.

You can use the API both in your own scripts and in the “Execute JavaScript” action.

the API contains 27 additional functions.

Quick list of functions:

ccbPrintDebug,   ccbGetNodeUnderMouse, ccbGetOverlayUnderMouse, ccbGetParentNodeOf, ccbGetNodesByName, ccbSetAllNodesInvisibleByName, ccbSetAllNodesVisibleByName, ccbToggleVisibilityByName, ccbCountAllNodes, ccbCleanProcessMemory, ccbGarbageCollector, ccbSetMaterialPropertyAll, ccbSetTextureAllMaterials, ccbFormatMsToMMSS, ccbFindClosestNode, ccbAlignNodeToGround, ccbSnapNodeToGrid, ccbFindMaterialUsage, ccbFindNodesByMaterial, ccbAIMoveToNode, ccbAIMoveToCord, ccbSetOverlayNodePositionPercent, ccbSetOverlayNodePositionPixels, ccbSetOverlayNodeScalePercent, ccbSetOverlayNodeScalePixels, ccbBillboardAboveAllNodes, ccbCalculateDistance

ccbPrintDebug(obj, msg)

Signature: ccbPrintDebug(obj, msg)
Description: Conditional logger. Prints msg if obj.ShowOutput === true. If obj lacks ShowOutput, it falls back to a global variable #ccbAPI_Debug (if #ccbAPI_Debug === "1" it prints).
Return: none.
Example:

ccbPrintDebug(this, "Player health: " + playerHp); 

ccbGetNodeUnderMouse(debug)

Signature: ccbGetNodeUnderMouse(debug)
Description: Attempts to return the 3D scene node under the mouse cursor. Multiple fallback strategies:

• tries ccbGet3DPosFrom2DPos(mx, my, depth) to get near/far ray endpoints and then ccbGetCollisionPointOfWorldWithLine.

• if not available, builds a ray using the active camera (camera position → target).

• if still not found, does a scene traversal using ccbDoesLineCollideWithBoundingBoxOfSceneNode for each node (slow). Parameters: debug (bool) to print diagnostic messages.
  Return: the scene node reference under cursor or null.
  Example:

var node = ccbGetNodeUnderMouse(true); if (node) print(ccbGetSceneNodeProperty(node,"Name")); 

ccbGetOverlayUnderMouse(debug)

Signature: ccbGetOverlayUnderMouse(debug)
Description: Traverses scene nodes, identifying 2D overlays by checking Position Mode and overlay size properties (percent/pixels). Returns overlay node under the mouse cursor.
Return: overlay node or null.
Example:

var ov = ccbGetOverlayUnderMouse(true); if (ov) ccbSetSceneNodeProperty(ov, "Visible", false); 

ccbGetParentNodeOf(childNode)

Signature: ccbGetParentNodeOf(childNode)
Description: Finds and returns the parent node of childNode by recursively traversing the scenegraph. Useful on target builds which lack direct parent getter.
Return: parent node or null.
Example:

var parent = ccbGetParentNodeOf(myNode); 

ccbGetNodesByName(name)

Signature: ccbGetNodesByName(name)
Description: Returns an array of all scene nodes whose Name equals name. Performs a full scene traversal.
Return: Array of nodes (possibly empty).
Example:

var list = ccbGetNodesByName("CubeMesh1"); for (var i=0;i<list.length;i++) ccbSetSceneNodeProperty(list[i], "Visible", false); 

ccbSetAllNodesInvisibleByName(name) / ccbSetAllNodesVisibleByName(name) / ccbToggleVisibilityByName(name)

Signatures: same as names suggest.
Description: Helpers that operate on all nodes found by ccbGetNodesByName and set Visible=false, Visible=true, or toggle it.
Return: number of nodes affected.
Example:

ccbSetAllNodesInvisibleByName("CubeMesh"); 

ccbCountAllNodes()

Signature: ccbCountAllNodes()
Description: Traverses the whole scene and returns node count. May be expensive on huge scenes.
Return: integer count.
Example:

print("Total nodes: " + ccbCountAllNodes()); 

ccbCleanProcessMemory(ProcessName, ShowOutput)

Signature: ccbCleanProcessMemory(ProcessName, ShowOutput)
Description: Windows-only helper: builds a PowerShell script and runs it via system() with -EncodedCommand to call SetProcessWorkingSetSize on process(es) with given name. Performs GC calls inside script and tries to reduce the working set.
Notes & limitations:

• Only works on Windows and only if system() is available.

• May require elevated permissions; AV may block it.

• If ProcessName ends with .exe the .exe suffix is removed automatically. Example:

ccbCleanProcessMemory("gameprocessname", true);

ccbGarbageCollector(debuggc)

Signature: ccbGarbageCollector(debuggc)
Description: Attempts to call exposed garbage-collector functions (best effort): gc(), CollectGarbage(), global.gc(). Prints debug if available. Many runtimes do not expose direct GC call — this is best-effort only.
Example:

ccbGarbageCollector(true); 

ccbSetMaterialPropertyAll(node, propName, value)

Signature: ccbSetMaterialPropertyAll(node, propName, value)
Description: Sets a material property (for example "ZBuffer", "Texture1") for every material index of node. Returns how many materials were updated.
Example:

ccbSetMaterialPropertyAll(myNode, "ZBuffer", 0); 

ccbSetTextureAllMaterials(node, texture, slotName)

Signature: ccbSetTextureAllMaterials(node, texture, slotName)
Description: Convenience wrapper to set texture slot (default "Texture1") on all materials of a node. Returns count.
Example:

ccbSetTextureAllMaterials(myNode, "mydiff.png"); 

ccbFormatMsToMMSS(ms)

Signature: ccbFormatMsToMMSS(ms)
Description: Formats milliseconds into M:SS. Safe and simple.
Return: string like 1:05.
Example:

var s = ccbFormatMsToMMSS(65000); // "1:05" 

ccbFindClosestNode(point, nameFilterFn)

Signature: ccbFindClosestNode(point, nameFilterFn)
Description: Finds the scene node closest to point = {x,y,z}. Optional nameFilterFn(name) can be provided to skip nodes (function returns true to include). Uses PositionAbs where available.
Return: node reference or null.
Example:

var nearest = ccbFindClosestNode({x:10,y:0,z:5}, function(nm){ return nm.indexOf("enemy")===0; }); 

ccbAlignNodeToGround(node, rayOriginOffset, maxDropDistance)

Signature: ccbAlignNodeToGround(node, rayOriginOffset, maxDropDistance)
Description: Casts a vertical ray from node (plus rayOriginOffset) downwards up to maxDropDistance, finds the collision with the world and positions the node at the hit point. Returns true on success. Depends on ccbGetCollisionPointOfWorldWithLine.
Example:

ccbAlignNodeToGround(myNode, {x:0,y:50,z:0}, 200); 

ccbSnapNodeToGrid(node, gridSize, worldSpaceBool)

Signature: ccbSnapNodeToGrid(node, gridSize, worldSpaceBool)
Description: Snaps node position to nearest grid cell. If worldSpaceBool is true tries to use PositionAbs and ccbSetSceneNodePositionWithoutCollision. Returns snapped position {x,y,z} or null on failure.
Example:

ccbSnapNodeToGrid(myNode, 1.0, true); 

ccbFindMaterialUsage(materialRef) / ccbFindNodesByMaterial(materialRef)

Signature: both ccbFindMaterialUsage(materialRef) and ccbFindNodesByMaterial(materialRef)
Description: Scan scene and return where a material (or texture name) is used. ccbFindMaterialUsage returns details per material slot { node, materialIndex, matchedSlot }. ccbFindNodesByMaterial returns node list. Useful to change or debug shared materials.
Example:

var uses = ccbFindMaterialUsage("stone.png"); 

ccbAIMoveToNode(NodeToMove, TargetNode, MoveSpeed, ArrivalDistance, onArrival)

Signature: ccbAIMoveToNode(NodeToMove, TargetNode, MoveSpeed, ArrivalDistance, onArrival)
Description: Creates and starts an on-frame controller to move NodeToMove towards TargetNode smoothly. Speed is FPS-independent, rotates the mover to face the target (yaw on Y axis), and snaps on arrival. onArrival may be a JS callback or CopperCube action reference. Returns controller object with start(), stop() and isRunning() methods.
Example:

ccbAIMoveToNode(enemyNode, playerNode, 2.0, 0.5, function(me,target){ ccbInvokeAction(attackAction, me); }); 

ccbAIMoveToCord(NodeToMove, target, moveSpeed, arrivalDistance, onArrival)

Signature: ccbAIMoveToCord(NodeToMove, target, moveSpeed, arrivalDistance, onArrival)
Description: Similar to ccbAIMoveToNode but target can be a node, a string like "10,0,5", "{10,0,5}" or [x,y,z]. Returns a handle with stop() and read-only isArrived. Note: implementation multiplies speed by 25 for compatibility with older code (you can adjust).
Example:

ccbAIMoveToCord(AINode, "10,0,5", 0.4, 0.2, myActionRef); 

Overlay helpers

• ccbSetOverlayNodePositionPercent(OverlayNode, PosX, PosY) — set overlay position in percent.

• ccbSetOverlayNodePositionPixels(OverlayNode, PosX, PosY) — set overlay position in pixels.

• ccbSetOverlayNodeScalePercent(OverlayNode, width, height) — set overlay size in percent.

• ccbSetOverlayNodeScalePixels(OverlayNode, width, height) — set overlay size in pixels.
  Example:

ccbSetOverlayNodePositionPercent(myOverlay, 50, 50); ccbSetOverlayNodeScalePixels(myOverlay, 200, 32); 

ccbBillboardAboveAllNodes(BillboardNode, above)

Signature: ccbBillboardAboveAllNodes(BillboardNode, above)
Description: Sets material ZBuffer for all materials of BillboardNode. If above is undefined or true then ZBuffer=0 (render above). If above=false then ZBuffer=1. Returns number of materials touched in robust implementations.
Example:

ccbBillboardAboveAllNodes(myBillboard); // default above=true ccbBillboardAboveAllNodes(myBillboard, false); // restore 

ccbCalculateDistance(node1, node2)

Signature: ccbCalculateDistance(node1, node2)
Description: Returns Euclidean distance between two {x,y,z} objects or positions (just x/y/z numbers). Simple helper.
Example:

var d = ccbCalculateDistance({x:0,y:0,z:0}, {x:3,y:4,z:0}); // 5

Performance & best practices

• Avoid full-scene scans every frame. Use ccbGetNodesByName and cache results where possible.

• Throttle expensive actions. Only call heavy functions (material searches, ccbCountAllNodes) during load screens or developer tools.

• Use ccbRegisterOnFrameEvent carefully. Registered frame callbacks can kill performance if they do heavy work each tick. Throttle with time checks.

• Test on target platform. WebGL and native player behave differently: system() and PowerShell methods only work on native builds.

Target compatibility & limitations

• Browser/WebGL: no system() (PowerShell) calls. Many editor-only calls are not available. navigator.clipboard might be available but needs user gesture & HTTPS.

• Desktop (Windows/Linux/macOS): system() generally available depending on how you package the game. PowerShell trimming is Windows-only.

• Editor-only functions (editorGetSelectedSceneNode, editor...): do not use inside runtime actions / players.

Security & permissions

• Functions invoking OS commands (ccbCleanProcessMemory) are sensitive: they may be blocked by AV, require admin rights, and look suspicious. Use sparingly and inform end-users.

• ccbGarbageCollector is best-effort and will silently no-op where not available.