Refactor Lua API

.clang-format

@@ -26,14 +26,14 @@ AlignConsecutiveShortCaseStatements:
 AllowAllArgumentsOnNextLine: true
 AllowBreakBeforeNoexceptSpecifier: OnlyWithParen
 AlignEscapedNewlines: Left
-AllowShortBlocksOnASingleLine: Always
+AllowShortBlocksOnASingleLine: Never
 AllowShortCaseExpressionOnASingleLine: true
 AllowShortCompoundRequirementOnASingleLine: true
 AllowShortEnumsOnASingleLine: true
 AllowShortNamespacesOnASingleLine: true
-AllowShortCaseLabelsOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: true
 AllowShortIfStatementsOnASingleLine: AllIfsAndElse
-AllowShortLoopsOnASingleLine: true
+AllowShortLoopsOnASingleLine: false
 # AllowShortRecordOnASingleLine = Always # v23
 AlwaysBreakTemplateDeclarations: true
 BreakAdjacentStringLiterals: false
@@ -85,11 +85,12 @@ IndentExportBlock: true
 IndentExternBlock: true
 IndentPPDirectives: BeforeHash
 IndentRequiresClause: false
+InsertBraces: false
+InsertNewlineAtEOF: false
 IntegerLiteralSeparator:
     Decimal: 3
 IncludeBlocks:   Merge
 IncludeIsMainRegex: '$'
-InsertNewlineAtEOF: true
 LambdaBodyIndentation: Signature
 ReflowComments: Always
 RequiresClausePosition: WithPreceding

.clang-tidy

@@ -6,7 +6,9 @@ Checks: >
     cert-*,
     performance-*,
     -bugprone-switch-missing-default-case,
-    -bugprone-easily-swappable-parameters
+    -bugprone-easily-swappable-parameters,
+    -clang-diagnostic-gnu-statement-expression,
+    -clang-diagnostic-gnu-statement-expression-from-macro-expansion
 # readability-*
 # modernize-*,
 # cppcoreguidelines-*,

.gitignore

@@ -25,6 +25,7 @@ out/
 
 *.bak
 *.tmp
+*.old
 
 # Prerequisites
 *.d

CMakeLists.txt

@@ -42,26 +42,20 @@ if (BUILD_TESTS)
 endif ()
 
 add_subdirectory (core)
+add_subdirectory (game)
 add_subdirectory (sys)
 add_subdirectory (gfx)
 add_subdirectory (app)
-add_subdirectory (game)
 
 add_library(project_warnings INTERFACE)
 
-if (MSVC)
-  target_compile_options(project_warnings INTERFACE /W4)
-else ()
-  target_compile_options(project_warnings INTERFACE -Wall -Wextra -Wpedantic)
-endif()
+target_compile_options(project_warnings INTERFACE -Wall -Wextra -Wpedantic -fno-exceptions)
 
 if (ENABLE_DEEP_ANALYSIS)
-  if (MSVC)
-    target_compile_options (project_warnings INTERFACE /analyze)
-  elseif (CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+  if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
     target_compile_options (project_warnings INTERFACE -fanalyzer)
   else ()
-    message (FATAL_ERROR "ENABLE_DEEP_ANALYSIS is ON, but ${CMAKE_CXX_COMPILER_ID} doesn't have an analyzer.")
+    message (FATAL_ERROR "ENABLE_DEEP_ANALYSIS requires the GCC compiler.")
   endif ()
 endif ()
 

README.md

@@ -6,7 +6,7 @@ This is the early development of a game and engine built from scratch in C++23.
 
 ### Toolchain
 
-- A C++23 compiler: GCC 14+, Clang 17+, or MSVC 19.38+
+- A C++23 compiler that supports GNU statement expressions: GCC 14+, Clang 19+
 - [CMake](https://cmake.org/) 3.25+
 - [Lua](https://www.lua.org/) 5.4+
 

app/CMakeLists.txt

@@ -1,14 +1,21 @@
-add_library (app)
+find_package(Lua 5.4 REQUIRED)
 
-target_include_directories (
+add_library(app)
+
+target_include_directories(
   app
+  PRIVATE ${LUA_INCLUDE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/src
   PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include
 )
 
-target_link_libraries (
+target_link_libraries(
   app
-  PRIVATE sys gfx
-  PUBLIC core game
+  PRIVATE ${LUA_LIBRARIES}
+  PUBLIC game gfx
 )
 
-add_subdirectory (src)
+add_subdirectory(src)
+
+if (BUILD_TESTS)
+  add_subdirectory(tests)
+endif ()

app/include/app/content.hh

@@ -0,0 +1,28 @@
+#pragma once
+#include "app/sprite.hh"
+#include "core/basic-catalog.hh"
+#include "gfx/texture.hh"
+#include <string_view>
+#include <vector>
+
+struct Renderer;
+
+namespace Game { struct World; }
+
+namespace App {
+  using Assets  = TypeList<Texture>;
+  using Catalog = BasicCatalog<Assets>; // labeled by file path
+
+  // The presentation of content definitions.
+  struct Visuals
+  {
+    Catalog             assets;
+    std::vector<Sprite> terrain; // parallel to the world's terrain definitions
+  };
+
+  // Runs the Lua content script at the path, then compiles the definitions it authored into the
+  // world's catalog and their presentation into the visuals. Diagnostics are printed to stdout.
+  // Returns false if the script failed or any definition could not be compiled.
+  [[nodiscard]] bool
+  load_content(std::string_view path, Game::World& world, Renderer& renderer, Visuals& visuals);
+}

app/include/app/keyboard-pilot.hh

@@ -0,0 +1,17 @@
+#pragma once
+#include "app/pilot.hh"
+#include "sys/keyboard.hh"
+#include "sys/mouse.hh"
+
+namespace App {
+  struct KeyboardPilot : Pilot
+  {
+    void handle_event(SDL_Event const& event) override;
+    void steer(Game::World const&, Game::CommandBuffer& out, Game::Entity entity) override;
+
+  private:
+
+    Keyboard keyboard_;
+    Mouse    mouse_;
+  };
+}

app/include/app/lua/key.hh

@@ -0,0 +1,47 @@
+#pragma once
+#include "app/lua/types.hh"
+#include "core/panic.hh"
+#include <string_view>
+
+namespace Lua {
+
+  // Identifies a field of a table by name or by integer index.
+  // Note: Key does not own or manage a copy of the string value. It holds a string view.
+  struct Key
+  {
+    enum class Kind : u8 { Index, Name };
+
+    constexpr Key(char const* name) noexcept : kind_{ Kind::Name }, name_{ name } {}
+
+    constexpr Key(std::string_view name) noexcept : kind_{ Kind::Name }, name_{ name } {}
+
+    constexpr Key(Integer index) noexcept : kind_{ Kind::Index }, index_{ index } {}
+
+    constexpr Key(int index) noexcept : Key(Integer{ index }) {}
+
+    [[nodiscard]] constexpr std::string_view as_name() const noexcept
+    {
+      DEBUG_ASSERT(kind_ == Kind::Name);
+      return name_;
+    }
+
+    [[nodiscard]] constexpr Integer as_index() const noexcept
+    {
+      DEBUG_ASSERT(kind_ == Kind::Index);
+      return index_;
+    }
+
+    [[nodiscard]] constexpr bool is_index() const noexcept { return kind_ == Kind::Index; }
+
+    [[nodiscard]] constexpr bool is_name() const noexcept { return kind_ == Kind::Name; }
+
+    [[nodiscard]] constexpr Kind kind() const noexcept { return kind_; }
+
+  private:
+
+    Kind             kind_  = Kind::Index;
+    Integer          index_ = 0;
+    std::string_view name_  = {};
+  };
+
+} // namespace Lua

app/include/app/lua/reference.hh

@@ -0,0 +1,45 @@
+#pragma once
+#include "app/lua/types.hh"
+
+struct lua_State;
+
+namespace Lua {
+
+  // Owns a slot in the Lua registry that keeps a value alive.
+  // Must not outlive the state that created it.
+  struct Reference
+  {
+    // Pops the value on the top of the stack into a new reference.
+    [[nodiscard]] static Reference pop(lua_State* L) noexcept;
+
+    Reference() noexcept = default;
+    Reference(Reference const&) noexcept;
+    Reference(Reference&&) noexcept;
+    Reference& operator=(Reference const&) noexcept;
+    Reference& operator=(Reference&&) noexcept;
+    ~Reference() noexcept;
+
+    // Returns true if both refer to the same Lua value (raw equality).
+    friend bool operator==(Reference const& l, Reference const& r) noexcept;
+
+    [[nodiscard]] Type type() const noexcept { return type_; }
+
+    [[nodiscard]] lua_State* state() const noexcept { return state_; }
+
+    // Pushes the referenced value onto the top of the stack and returns its stack index.
+    int push() const noexcept;
+
+  private:
+
+    Reference(lua_State* L, int ridx, Type type) noexcept;
+
+    void release() noexcept;
+
+    static constexpr int no_ref = -2; // LUA_NOREF
+
+    lua_State* state_ = nullptr; // non-owning pointer
+    int        ridx_  = no_ref;
+    Type       type_  = Type::None;
+  };
+
+} // namespace Lua

app/include/app/lua/state.hh

@@ -0,0 +1,45 @@
+#pragma once
+#include "app/lua/table.hh"
+#include <optional>
+#include <string>
+#include <string_view>
+
+struct lua_State;
+
+namespace Lua {
+
+  // Owns a sandboxed Lua state: only the base, table, string, math, and utf8 libraries are opened.
+  // Failures print a diagnostic.
+  struct State
+  {
+    [[nodiscard]] static std::optional<State> create();
+
+    State() noexcept               = default;
+    State(State const&)            = delete;
+    State& operator=(State const&) = delete;
+
+    State(State&&) noexcept;
+    State& operator=(State&&) noexcept;
+    ~State() noexcept;
+
+    // Runs the file at the given path.
+    [[nodiscard]] bool load(std::string_view path);
+
+    // Runs the source code, using the name to identify the chunk in diagnostics.
+    [[nodiscard]] bool execute(std::string_view name, std::string_view source);
+
+    [[nodiscard]] Table globals() const;
+
+    // The path is used to identify the table and its fields in diagnostics.
+    [[nodiscard]] Table create_table(std::string path = {}) const;
+
+    [[nodiscard]] lua_State* get() const noexcept { return handle_; }
+
+  private:
+
+    explicit State(lua_State*) noexcept;
+
+    lua_State* handle_ = nullptr;
+  };
+
+} // namespace Lua