docs: start doxygen

.github/workflows/CI.yml

@@ -3,10 +3,12 @@ name: CI
 on:
   workflow_dispatch:
   push:
-    paths:
-      - 'src/*'
-      - 'tests/*'
-      - '.github/workflows/CI.yml'
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+      - develop
 
 jobs:
   test:

.github/workflows/DOCS.yml

@@ -0,0 +1,31 @@
+name: DOCS
+
+env:
+  CLOUDFLARE_PROJECT_DOXYGEN: doxygen-engine
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  doxygen:
+    runs-on: ubuntu-latest
+    steps:
+      - 
+        uses: actions/checkout@master
+      - 
+        run: |
+          docker run --rm -v $(pwd):/app -w /app rodrigodornelles/doxygen:lua doxygen
+      - 
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: ${{ env.CLOUDFLARE_PROJECT_DOXYGEN }}
+          directory: html

.gitignore

@@ -1,3 +1,5 @@
 luacov.*
 vendor/
-dist/
+dist/
+html/
+latex/

Doxyfile

@@ -0,0 +1,41 @@
+# Custom Configs
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "Engine"
+PROJECT_NUMBER         = 0.0.2
+PROJECT_BRIEF          = "Game engine in lua"
+PROJECT_LOGO           = 
+OUTPUT_DIRECTORY       = .
+RECURSIVE              = YES
+CREATE_SUBDIRS         = NO
+STRIP_CODE_COMMENTS    = NO
+CALL_GRAPH             = YES
+HAVE_DOT               = YES
+EXTRACT_ALL            = YES
+USE_MATHJAX            = YES
+EXTRACT_STATIC         = NO
+SHORT_NAMES            = YES
+INLINE_GROUPED_CLASSES = YES
+INLINE_SIMPLE_STRUCTS  = YES
+TYPEDEF_HIDES_STRUCT   = YES
+SOURCE_BROWSER         = YES
+VERBATIM_HEADERS       = NO
+PREDEFINED             = DOXYGEN=
+PLANTUML_JAR_PATH      = $(PLANTUML_JAR_PATH)
+PLANTUML_CFG_FILE      =
+PLANTUML_INCLUDE_PATH  =
+OUTPUT_LANGUAGE        = English
+FILE_PATTERNS          = *.lua
+FILTER_PATTERNS        = *.lua=lua2dox
+EXTENSION_MAPPING      = .lua=C++
+INPUT                  = README.md SUPPORT.md src examples
+USE_MDFILE_AS_MAINPAGE = README.md
+MARKDOWN_ID_STYLE      = GITHUB
+ALIASES               += startebnf=@startuml{ebnf}
+ALIASES               += endebnf=@enduml
+# Theme: https://jothepro.github.io/doxygen-awesome-css/
+GENERATE_TREEVIEW      = YES
+DISABLE_INDEX          = NO
+FULL_SIDEBAR           = NO
+HTML_EXTRA_STYLESHEET  = $(DOXYGEN_AWESOME_PATH)/doxygen-awesome.css \
+                         $(DOXYGEN_AWESOME_PATH)/doxygen-awesome-sidebar-only.css
+HTML_COLORSTYLE        = LIGHT

examples/asteroids/game.lua

@@ -11,7 +11,7 @@
 --! state 8 as "menu"
 --! 
 --! [*] -> 1
---! 1 --> 2
+--! 1 ---> 2
 --! 1 --> 3
 --! 2 --> 1
 --! 3 --> 4

src/cli/init.lua

@@ -1,16 +1,18 @@
 local os = require('os')
-local args = require('src/shared/args')
+local zeebo_args = require('src/shared/args')
 
-local run = args.has(arg, 'run')
-local coverage = args.has(arg, 'coverage')
-local game = args.get(arg, 'game', './examples/pong')
-local core = args.get(arg, 'core', 'ginga')
-local screen = args.get(arg, 'screen', '1280x720')
-local command = args.param(arg, {'game', 'core', 'screen'}, 1, 'help')
+--! @cond
+local run = zeebo_args.has(arg, 'run')
+local coverage = zeebo_args.has(arg, 'coverage')
+local game = zeebo_args.get(arg, 'game', './examples/pong')
+local core = zeebo_args.get(arg, 'core', 'ginga')
+local screen = zeebo_args.get(arg, 'screen', '1280x720')
+local command = zeebo_args.param(arg, {'game', 'core', 'screen'}, 1, 'help')
 
 if command == 'test-self' then
     coverage = coverage and '-lluacov' or ''
-    local ok = os.execute('lua '..coverage..' ./tests/*.lua')
+    local ok = os.execute('lua '..coverage..' ./tests/test_lib_common_math.lua')
+    local ok = ok and os.execute('lua '..coverage..' ./tests/test_shared_args.lua')
     if #coverage > 0 then
         os.execute('luacov src')
     end
@@ -27,8 +29,9 @@ elseif command == 'build' then
 
     -- move common lib
     os.execute('cp src/lib/common/*.lua dist')
+    os.execute('cp src/object/application.lua dist/src_object_application.lua')
     os.execute('cp src/object/game.lua dist/src_object_game.lua')
-    os.execute('cp src/object/keys.lua dist/src_object_keys.lua')
+    os.execute('cp src/object/std.lua dist/src_object_std.lua')
     os.execute('cp src/shared/*.lua dist')
 
     -- move engine
@@ -57,3 +60,5 @@ else
     print('command not found: '..command)
     os.exit(1)
 end
+
+--! @endcond

src/lib/common/lib_math.lua

@@ -1,8 +1,13 @@
-local function clamp(value, min, max)
-    if value < min then
-        return min
-    elseif value > max then
-        return max
+--! @defgroup std
+--! @{
+--! @defgroup math
+--! @{
+
+local function clamp(value, value_min, value_max)
+    if value < value_min then
+        return value_min
+    elseif value > value_max then
+        return value_max
     else
         return value
     end
@@ -30,27 +35,27 @@ local function abs(value)
     return value
 end
 
-local function saw(x)
-    if x < 0.25 then
-        return x * 4
-    elseif x < 0.50 then
-        return 1 - ((x - 0.25) * 4)
-    elseif x < 0.75 then
-        return ((x - 0.50) * 4) * (-1)
+local function saw(value)
+    if value < 0.25 then
+        return value * 4
+    elseif value < 0.50 then
+        return 1 - ((value - 0.25) * 4)
+    elseif value < 0.75 then
+        return ((value - 0.50) * 4) * (-1)
     end
-    return ((x - 0.75) * 4) - 1
+    return ((value - 0.75) * 4) - 1
 end
 
 local function lerp(a, b, alpha)
     return a + alpha * ( b - a )
 end 
 
-local function map(x, in_min, in_max, out_min, out_max)
-    return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min
+local function map(value, in_min, in_max, out_min, out_max)
+    return (value - in_min) * (out_max - out_min) / (in_max - in_min) + out_min
 end
 
-local function clamp2(value, min, max)
-    return (value - min) % (max - min + 1) + min
+local function clamp2(value, value_min, value_max)
+    return (value - value_min) % (value_max - value_min + 1) + value_min
 end
 
 local function cycle(passed, duration)
@@ -79,6 +84,9 @@ local function max(...)
     return max_value
 end
 
+--! @}
+--! @}
+
 local P = {
     cycle=cycle,
     clamp=clamp,
@@ -88,7 +96,8 @@ local P = {
     map=map,
     dis=dis,
     saw=saw,
-    max=max
+    max=max,
+    dir=dir
 }
 
 return P;

src/lib/ginga/core.lua

@@ -1,12 +1,18 @@
-local mathstd = require('math')
-local game = require('game')
-local math = require('lib_math')
+local math = require('math')
+local application = require('game')
+local zeebo_math = require('lib_math')
 local decorators = require('decorators')
+local game = require('src_object_game')
+local std = require('src_object_std')
+local fixture190 = ''
+
+--! @short nclua:canvas
+--! @li <http://www.telemidia.puc-rio.br/~francisco/nclua/referencia/canvas.html>
 local canvas = canvas
+
+--! @short nclua:event
+--! @li <http://www.telemidia.puc-rio.br/~francisco/nclua/referencia/event.html>
 local event = event
-local game_obj = {meta={}, config={}, callbacks={}}
-local std = {draw={},key={press={}},game={}}
-local fixture190 = ''
 
 -- key mappings
 local key_bindings={
@@ -37,25 +43,25 @@ _ENV = nil
 
 local function std_draw_fps(x, y)
     canvas:attrColor('yellow')
-    if game_obj.fps_show >= 1 then
+    if game.fps_show >= 1 then
         canvas:drawRect('fill', x, y, 40, 24)
     end
-    if game_obj.fps_show >= 2 then
+    if game.fps_show >= 2 then
         canvas:drawRect('fill', x + 48, y, 40, 24)
     end
     canvas:attrColor('black')
     canvas:attrFont('Tiresias', 16)
-    if game_obj.fps_show >= 1 then
+    if game.fps_show >= 1 then
         canvas:drawText(x + 2, y, fps_obj.total)
     end
-    if game_obj.fps_show >= 1 then
-        canvas:drawText(x + 50, y, game_obj.fps_max)
+    if game.fps_show >= 1 then
+        canvas:drawText(x + 50, y, game.fps_max)
     end
 end
 
 local function std_draw_clear(color)
     canvas:attrColor(color)
-    canvas:drawRect('fill', 0, 0, game_obj.width, game_obj.height)
+    canvas:drawRect('fill', 0, 0, game.width, game.height)
 end
 
 local function std_draw_color(color)
@@ -86,17 +92,17 @@ local function std_draw_line(x1, y1, x2, y2)
 end
 
 local function std_game_reset()
-    if game.callbacks.exit then
-        game.callbacks.exit(std, game_obj)
+    if application.callbacks.exit then
+        application.callbacks.exit(std, game)
     end
-    if game.callbacks.init then
-        game.callbacks.init(std, game_obj)
+    if application.callbacks.init then
+        application.callbacks.init(std, game)
     end
 end
 
 local function std_game_exit()
-    if game.callbacks.exit then
-        game.callbacks.exit(std, game_obj)
+    if application.callbacks.exit then
+        application.callbacks.exit(std, game)
     end
     event.post({class="ncl", type="stop"})
 end
@@ -105,7 +111,7 @@ local function event_loop(evt)
     if evt.class ~= 'key' then return end
     if not key_bindings[evt.key] then return end
 
-    -- https://github.com/TeleMidia/ginga/issues/190
+    --! @li https://github.com/TeleMidia/ginga/issues/190
     if #fixture190 == 0 and evt.key ~= 'ENTER' then
         fixture190 = evt.type
     end
@@ -119,59 +125,48 @@ end
 
 local function fixed_loop()
     -- internal clock 
-    game_obj.milis = event.uptime()
-    game_obj.fps = fps_obj.total
-    game_obj.dt = fps_obj.delta 
-    if not fps.counter(game_obj.fps_max, fps_obj, game_obj.milis) then
-        game_obj.fps_max = fps_dropper[game_obj.fps_max]
+    game.milis = event.uptime()
+    game.fps = fps_obj.total
+    game.dt = fps_obj.delta 
+    if not fps.counter(game.fps_max, fps_obj, game.milis) then
+        game.fps_max = fps_dropper[game.fps_max]
     end
 
     -- game loop
-    game.callbacks.loop(std, game_obj)
+    application.callbacks.loop(std, game)
 
     -- game render
     canvas:attrColor(0, 0, 0, 0)
     canvas:clear()
-    game.callbacks.draw(std, game_obj)
+    application.callbacks.draw(std, game)
     std_draw_fps(8,8)
     canvas:flush()
 
     -- internal loop
-    event.timer(fps_limiter[game_obj.fps_max], fixed_loop)
+    event.timer(fps_limiter[game.fps_max], fixed_loop)
 end
 
 local function setup(evt)
     if evt.class ~= 'ncl' or evt.action ~= 'start' then return end
     local w, h = canvas:attrSize()
-    std.math=math
-    std.math.random = mathstd.random
+    std.math=zeebo_math
+    std.math.random = math.random
     std.draw.clear=std_draw_clear
     std.draw.color=std_draw_color
     std.draw.rect=std_draw_rect
     std.draw.text=std_draw_text
     std.draw.font=std_draw_font
     std.draw.line=std_draw_line
     std.draw.poly=decorators.poly(0, nil, std_draw_line)
-    std.key.press.up=0
-    std.key.press.down=0
-    std.key.press.left=0
-    std.key.press.right=0
-    std.key.press.red=0
-    std.key.press.green=0
-    std.key.press.yellow=0
-    std.key.press.blue=0
-    std.key.press.enter=0
     std.game.reset=std_game_reset
     std.game.exit=std_game_exit
-    game_obj.width=w
-    game_obj.height=h
-    game_obj.milis=0
-    game_obj.fps=0
-    game_obj.fps_max = game.config and game.config.fps_max or 100
-    game_obj.fps_show = game.config and game.config.fps_max or 0
-    fps_obj.drop_time = game.config and game.config.fps_time or 1
-    fps_obj.drop_count = game.config and game.config.fps_drop or 2
-    game.callbacks.init(std, game_obj)
+    game.width=w
+    game.height=h
+    game.fps_max = application.config and application.config.fps_max or 100
+    game.fps_show = application.config and application.config.fps_max or 0
+    fps_obj.drop_time = application.config and application.config.fps_time or 1
+    fps_obj.drop_count = application.config and application.config.fps_drop or 2
+    application.callbacks.init(std, game)
     event.register(event_loop)
     event.timer(1, fixed_loop)
     event.unregister(setup)