merge: Peach 0.6.0

merge: Peach 0.6.0

Author: smokingplaya

.luarc.json

@@ -20,7 +20,8 @@
         "/**/"
   ],
   "Lua.diagnostics.disable": [
-    "duplicate-set-field"
+    "duplicate-set-field",
+    "invisible"
   ],
   "Lua.workspace.checkThirdParty": false,
     "diagnostics.globals": [

README.md

@@ -8,26 +8,30 @@ Each **package** is a self-contained unit — just like an addon — with built-
 
 ## Features
 - Modular **package-based** architecture
-- Built-in **dependency resolution**
+- Built-in **dependency managment**
+- Built-in configuration system with in-database saving
 - Flexible **OOP** utilities and core libraries
-- Expandable with **atomic.\*** modules (config, command, network, etc.)
+- Expandable with **atomic.\*** libraries (i18n, command, network, etc.)
 - Designed for both **addons** and **gamemodes**
 
+## Examples
+You can quickly view [examples](./examples/README.md) of packages (addons) made on Atomic Framework to understand how it works.
+
 ---
 
 ## Documentation
 Full documentation, API references, and examples are available here:
-👉 **[Atomic Framework Wiki](https://github.com/AtomicGmod/atomic-framework/wiki)**
+👉 **[Atomic Framework Wiki](https://github.com/TeamMeadows/atomic-framework/wiki)**
 
 ---
 
 ## Installation
+Simply place the framework in your `addons/` folder.
+Atomic will automatically load available packages.
+
 Optional dependencies:
 - For `atomic.mysql` → install [MySQLOO](https://github.com/FredyH/MySQLOO)
-- For `atomic.git` → install [gm_git](https://github.com/AtomicGmod/gm_git)
-
-Simply place the framework in your `addons/` folder.
-Atomic will automatically load and register available packages.
+- For `atomic.git` → install [gm_git](https://github.com/TeamMeadows/gm_git)
 
 ---
 
@@ -38,11 +42,6 @@ Discussions and proposals are also encouraged in the issue tracker.
 
 ---
 
-## Roadmap
-See [To Do](#) or the project’s issue tracker for current development progress.
-
----
-
 ## License
 This project is licensed under the **GNU General Public License v3.0**.
 See the [LICENSE](./LICENSE) file for more details.

examples/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+This subfolder contains drop-in packages that
+will show you how to work with Atomic Framework.
+
+You can just drop this folder (`examples`, not `lua`) in
+`GarrysModDS/garrysmod/addons/`, and it will work.
+
+* [Ping](./lua/atomic/packages/ping) — shows you how to work with packages, network, measure time

examples/lua/atomic/packages/ping/core/client.lua

@@ -0,0 +1,30 @@
+---@class ExamplePackagePing: Atomic.Package
+local package = atomic.package.current()
+
+--- this function will send
+--- an asynchronous network message to the server
+--- and wait for a response
+function package:ping()
+  local instant = atomic.time.newInstant()
+
+  coroutine.start(function()
+    local message = self:sendNetworkMessageAsync("Ping", {})
+
+    local ms = instant:elapsed():as_millis()
+
+    package.logger:debug("Server ping took %sms", ms)
+    package.logger:debug("Server response: %s", message.contentz)
+  end)
+end
+
+--- Removing console command
+--- when package will disabled
+---
+--- !!! it's optional
+package:listen("onDisable", function()
+  concommand.Remove("do_ping")
+end)
+
+concommand.Add("do_ping", function()
+	package:ping()
+end)

examples/lua/atomic/packages/ping/core/server.lua

@@ -0,0 +1,12 @@
+---@class ExamplePackagePing: Atomic.Package
+local package = atomic.package.current()
+
+package:onNetworkMessage(function(message)
+  local sender = message:getSender()
+
+  sender:ChatPrint("Pong!")
+
+  message:reply({
+    content = "Hello from server!"
+  })
+end, "Ping")

examples/lua/atomic/packages/ping/core/shared.lua

@@ -0,0 +1,9 @@
+---@class ExamplePackagePing: Atomic.Package
+local package = atomic.package.current()
+
+--- Registering new Network Schema
+--- that will be visible on both sides - on client and server
+package:networkSchema("Ping")
+  -- server will send to client
+  -- field "content" with type of string
+  :clientField("content", "string")

examples/lua/atomic/packages/ping/package.lua

@@ -0,0 +1,11 @@
+---@type Atomic.Package.Metadata
+return {
+  id = "team.meadows.example_ping",
+  title = "Example package - Ping",
+  version = "1.0.0",
+  files = {
+    client = { "core/client.lua" },
+    shared = { "core/shared.lua" },
+    server = { "core/server.lua" }
+  }
+}

lua/atomic/libraries/benchmark.lua

@@ -0,0 +1,54 @@
+atomic.benchmark = atomic.benchmark or {}
+
+local Instant = atomic.time.newInstant
+local Duration = atomic.time.newDuration
+
+---@class Atomic.BenchmarkResult
+---@field iterations Atomic.Time.Duration[]
+---@field average Atomic.Time.Duration
+---@field min Atomic.Time.Duration
+---@field max Atomic.Time.Duration
+
+---@param func function
+---@param opts? { repeats: number, warmup: number }
+---@return Atomic.BenchmarkResult
+function atomic.benchmark.run(func, opts)
+  opts = opts or { repeats = 1, warmup = 2 }
+  local repeats = opts.repeats or 1
+  local warmup = opts.warmup or 2
+
+  -- warmup
+  for i = 1, warmup do
+    func()
+  end
+
+  local iterations = {}
+
+  -- benchmark
+  for i = 1, repeats do
+    local start = Instant()
+    func()
+    iterations[#iterations+1] = start:elapsed()
+  end
+
+  -- statistic
+  local min = iterations[1]
+  local max = iterations[1]
+  local sum = Duration(0, 0)
+
+  for i = 1, #iterations do
+    local v = iterations[i]
+    if v < min then min = v end
+    if v > max then max = v end
+    sum = sum + v
+  end
+
+  local average = sum / #iterations
+
+  return {
+    iterations = iterations,
+    min = min,
+    max = max,
+    average = average
+  }
+end

lua/atomic/libraries/class.lua

@@ -5,10 +5,13 @@ atomic.class = atomic.class or {
       [atomic.meta.version] = {}
     }
   },
-
-  ---@type Atomic.Package
-  ---@diagnostic disable-next-line
-  pseudo = { id = "atomic", version = atomic.meta.version };
+  pseudo = {
+    _metadata = {
+      id = "atomic",
+      version = atomic.meta.version,
+      documentation = "https://github.com/TeamMeadows/atomic-framework/wiki",
+    }
+  }
 }
 
 ---@class Atomic.Class
@@ -30,7 +33,6 @@ function atomic.class.create(name, parent)
   local class = setmetatable({ _name = name }, { __index = parent or classMt })
   class.__index = class
   class.__tostring = function(self)
-    ---@diagnostic disable-next-line
     return "instance of " .. tostring(self._name)
   end
 
@@ -58,11 +60,11 @@ end
 ---@generic T
 ---@return T: Atomic.Class?
 function atomic.class.get(name, packageOrId, packageVersion)
-  local pkgName = type(packageOrId) == "table" and packageOrId.id
+  local pkgName = type(packageOrId) == "table" and packageOrId._metadata.id
       or type(packageOrId) == "string" and packageOrId
       or not packageOrId and "atomic"
 
-  local pkgVersion = type(packageOrId) == "table" and packageOrId.version
+  local pkgVersion = type(packageOrId) == "table" and packageOrId._metadata.version
       or type(packageVersion) == "string" and packageVersion
       or pkgName == "atomic" and atomic.meta.version
 
@@ -76,12 +78,11 @@ end
 --- ```
 ---
 ---@generic T
----@param class Atomic.Class
----@param tab T? Content of the instance
----@vararg any
+---@param class T: Atomic.Class
+---@vararg any Arguments to be passed to the class constructor
 ---@return T: Atomic.Class
-function atomic.class.new(class, tab, ...)
-  local instance = setmetatable(tab or {}, class)
+function atomic.class.new(class, ...)
+  local instance = setmetatable({}, class)
 
   if (type(instance.init) == "function") then
     instance:init(...)
@@ -125,7 +126,7 @@ end
 ---@param package Atomic.Package
 function atomic.class.register(class, package)
   local storage = atomic.class._storage
-  local id, version = package.id, package.version
+  local id, version = package._metadata.id, package._metadata.version
 
   if (type(storage[id]) ~= "table") then
     storage[id] = {}
@@ -135,7 +136,6 @@ function atomic.class.register(class, package)
     storage[id][version] = {}
   end
 
-  ---@diagnostic disable-next-line
   storage[id][version][class._name] = class
 
   atomic.class._storage = storage
@@ -145,7 +145,6 @@ function atomic.class.unregister(class, package)
   local storage = atomic.class._storage
   local id, version = package.id, package.version
 
-  ---@diagnostic disable-next-line
   storage[id][version][class._name] = nil
 
   atomic.class._storage = storage

lua/atomic/libraries/command/class.lua

@@ -7,12 +7,12 @@
 ---@field private _arguments {[1]: string, [2]: Atomic.Command.ArgumentKind}[]
 ---@field private _execute Atomic.Command.ExecuteFunc
 ---@field private _enabled boolean Internal
-local command = atomic.class.create("Command")
-atomic.class.register(command, atomic.class.pseudo)
+local Command = atomic.class.create("Command")
+atomic.class.register(Command, atomic.class.pseudo)
 
 ---@param name string
 ---@param permission string
-function command:init(name, permission)
+function Command:init(name, permission)
   self._name = name
   self._permission = permission
   self._arguments = {}
@@ -22,15 +22,15 @@ end
 ---@param name string
 ---@param kind Atomic.Command.ArgumentKind
 ---@return self
-function command:argument(name, kind)
+function Command:argument(name, kind)
 	self._arguments[#self._arguments + 1] = { name, kind }
 
 	return self
 end
 
 ---@param executable Atomic.Command.ExecuteFunc
 ---@return self
-function command:onExecute(executable)
+function Command:onExecute(executable)
 	self._execute = executable
 
 	return self
@@ -64,7 +64,7 @@ end
 ---@private
 ---@param executor Player
 ---@param arguments table<string, Atomic.Command.ArgumentKind>
-function command:doExecute(executor, arguments)
+function Command:doExecute(executor, arguments)
   if (not self._enabled) then
     return
   end
@@ -83,7 +83,7 @@ function command:doExecute(executor, arguments)
 end
 
 ---@param b boolean
-function command:setEnabled(b)
+function Command:setEnabled(b)
 	self._enabled = b
 
 	return self