refactor api.exec => api.ext.exec + better docs

README.md

@@ -18,7 +18,7 @@ The aim of this project is providing **one [XR Hypermedia browser](https://xrhf.
 * Nintendo 3DS, Switch, and Wii via [lovebrew](https://lovebrew.org/)
 * Handhelds: Steamdeck, Anbernic, Gameforce, Game Kiddy, Powkiddy (..and more) via [portmaster](https://portmaster.games/supported-devices.html)
 * Game emulators via [lutro](https://lutro.libretro.com/)
-* Embedded devices via lua and/oror [nelua](https://nelua.org)
+* Embedded devices via [nelua](https://nelua.io) or straightup [lua](https://lua.org) 
 
 ## very hackable extensions
 

api.md

@@ -1,4 +1,42 @@
+## API Reference
 
+<pre>
+<a href="">api</a>
+<a href="">api.parser.json</a>
+<a href="#api-parser-xml">api.parser.xml</a>
+<a href="">api.url</a>
+<a href="">api.util</a>
+<a href="">api.protocol</a>
+<a href="">api.ext.*</a>
+<a href="#api-ext-exec">api.ext.exec(fn, ,..)</a>
+<a href="https://bakpakin.github.io/tiny-ecs/doc">api.ecs</a>
+<a href="https://bakpakin.github.io/tiny-ecs/doc">api.world</a>
+</pre>
+
+## Entity Component System (ECS)
+
+Read the Full Documentation here <a href="https://bakpakin.github.io/tiny-ecs/doc">https://bakpakin.github.io/tiny-ecs/doc</a>
+
+> Below are some helper functions to make things more efficient 
+
+---
+
+**commit()**
+
+```lua 
+obj = { foo = "bar", mycomponent = { a = 1 } }
+api.ecs.add( api.world, obj )
+
+obj.foo = "flop"
+obj.commit('Xhappened') 
+-- commit notifies all systems to rebuild entitycache
+-- because normally systems filter on an entitycache (=fast)
+-- which would still rely on foo = "bar".
+-- Only do this when you actually need a system to pick 
+-- up on a change.
+```
+
+> also <a href="#api-ext-exec">api.ext.exec('Xhappened')</a> is called so extensions can respond to the change.
 
 ## api.parser.xml
 
@@ -40,3 +78,11 @@ util.traverseXML( xml:ParseXmlText(testXml),  function(node,raw)
 --   }
 end)
 ```
+
+## api.ext.exec
+
+This allows batch-firing a function on each extension (if exist)
+
+```lua
+api.ext.exec('init', 123, "foo") -- call .init(123,"foo") on each extension 
+```

src/ext/skeleton/main.lua

@@ -1,10 +1,13 @@
 local api = ...
+local ecs = api.ecs
 
 return {
   name = "skeleton",
   enabled = true,
 
-  init = function() end,
+  init = function() 
+    --api.ext.skeleton.extendECS()
+  end,
 
   update = function()
     local iui = api.iui
@@ -20,5 +23,25 @@ return {
     else
 
     end
+  end,
+
+  -- ECS API docs: https://bakpakin.github.io/tiny-ecs/doc
+  extendECS = function()
+
+    local exampleSystem = ecs.processingSystem({
+      updatethread = true,
+   -- drawthread = true
+      filter = ecs.requireAll('mycomponent'),
+      onAdd    = function(self,obj) print_r(obj)  end,
+      onRemove = function(self,obj) end,
+      process  = function(self,obj) end,
+    })
+    ecs.addSystem( api.world, exampleSystem )
+
+    -- add example entity object
+    local obj = { foo = "bar", mycomponent = { a = 1 } }
+    ecs.add( api.world, obj )
+    obj.commit() -- notify other systems to update entitycache
+
   end
 }

src/ext/xrfragments/main.lua

@@ -1,38 +1,24 @@
 local api = ...
+local ecs   = api.ecs
 local xrf = require("ext/xrfragments/lovr-xrf")
 local xrfsystem
 
 return {
   enabled = true,
-  init = function()
-    -- create a (ecs) system which detects add/remove entities
-    local ecs   = api.ecs
-    xrfsystem = ecs.system({
 
-      filter = ecs.requireAll('x', 'y', 'z', 'model'),
+  init = function() end,
-      nocache = true,
-      filterDynamic = true,
-
-      onAdd = function(self,obj)
-
-        if lovr ~= nil then 
-          xrf.traverseNodesContaining('href', obj, 
-            xrf.makeClickable( api.ecs.worldPhysics, 
-              function(obj, collider)
-                print(obj['name'] .. ".href => " .. obj['extras']['href'] )
-                api.world.add({collider = collider})
-              end
-            )
-          )
-        end
-      end,
-
-      onRemove = function(self,obj)
-
-      end
-
-    })
-    ecs.addSystem( api.world, xrfsystem )
 
+  on3DFile = function(obj)
+    if lovr ~= nil then 
+      xrf.traverseNodesContaining('href', obj, 
+        xrf.makeClickable( api.ecs.worldPhysics, 
+          function(obj, collider)
+            print(obj['name'] .. ".href => " .. obj['extras']['href'] )
+            api.world.add({collider = collider})
+          end
+        )
+      )
+    end
   end
+
 }

src/lovr/main.lua

@@ -39,7 +39,7 @@ function lovr.load()
 
     iui.load(backend)
 
-    api.exec( api.ext, "load")
+    api.ext.exec("load")
 
     if iui.idiom == "vr" then
         lovr.headset.setPassthrough("opaque")
@@ -50,7 +50,7 @@ function lovr.load()
 end
 
 function lovr.update(dt)
-    
+
     ecs.update( api.world, dt, ecs.filterUpdate )
 
     iui.beginFrame(dt)
@@ -59,7 +59,7 @@ function lovr.update(dt)
         -- In desktop mode, we use IUI's standard window API to fill the screen.
         iui.beginWindow(lovr.system.getWindowDimensions())
 
-        api.exec( api.ext, "update", dt)
+        api.ext.exec("update", dt)
 
         iui.endWindow()
 
@@ -69,7 +69,7 @@ function lovr.update(dt)
         if mainWindow:beginFrame() then
             iui.beginWindow(mainWindow.w, mainWindow.h)
 
-            api.exec( api.ext, "update", dt)
+            api.ext.exec("update", dt)
 
             iui.endWindow()
 
@@ -90,7 +90,7 @@ function lovr.draw(pass)
       pass:setClear(0.5, 0.5, 0.5)
     end
 
-    api.exec(api.ext, "draw",pass)
+    api.ext.exec("draw",pass)
     ecs.update( api.world, pass, ecs.filterDraw )
 
      -- Dot

src/main.lua

@@ -11,8 +11,9 @@ api = {
   ecs      = ecs,
   world    = ecs.world(),
   protocol = {},
-  ext      = {}, -- all extensions loaded from disk at runtime
+  ext      = { -- all extensions are loaded here from disk at runtime
-  exec     = function(...) util.exec(...) end -- calls function on each table item
+    exec   = function(...) util.exec(api.ext,...) end -- util function to call func on each extension 
+  }
 }
 
 local runtime
@@ -28,7 +29,7 @@ require( runtime.path .. "/main")
 util.loaddir( "ext",   api, api.ext )
 util.loaddir( "media", api, api.media )
 ecs.init()
-api.exec( api.ext, 'init')
+api.ext.exec('init')
 
 -- GLB URLS
 --local url='https://coderofsalvation.codeberg.page/xrfragment-haxe/example/assets/example.glb?bar=1&f=2#foo'
@@ -41,5 +42,4 @@ api.exec( api.ext, 'init')
 --local url = 'https://snips.sh/f/rHFLg-cewi?r=1' -- cube
 local url = 'https://snips.sh/f/_U5-XctEVE?r=1' -- cube, monkey, scene
 
-
 api.ecs.add( api.world, { URI = { url = url, method = 'GET', target = '_top' }  })

src/util.lua

@@ -12,15 +12,9 @@ util.loaddir = function( path, api, target)
 end
 
 util.exec = function(obj, fn,a,b,c,d,e,f)
-  foreach( obj,
+    foreach( obj,
-    when('enabled',true, util.call(fn,a,b,c,d,e,f) )
+      when('enabled',true, util.call(fn,a,b,c,d,e,f) )
-  )
+    )
-end
-
-function when(k,v,cb)
-  return function(kk,vv)
-    if vv[k] == v then cb(kk,vv) end
-  end
 end
 
 function util.merge(t1,t2)
@@ -141,10 +135,13 @@ end
 
 function when(k,v,cb)
   return function(kk,vv)
-    if vv[k] == v then cb(kk,vv) end
+    if type(vv) == 'table' then 
+      if vv[k] == v then cb(kk,vv) end
+    end
   end
 end
 
+
 function util.merge(t1,t2)
   local t3 = {}
   foreach( t1, function(k,v) t3[k] = v end)
@@ -179,7 +176,7 @@ util.commit = function(world, obj, api)
         end
       end
     end
-    api.exec( api.ext, extCb, obj)
+    api.ext.exec(extCb, obj)
   end
 end