Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(shader): #include "path" expansion in ShaderParser

esengine1e0e003b1042
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index bf2a02a9c..8b58d8a37 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -14,9 +14,77 @@
#include <sstream>
#include <algorithm>
+#include <unordered_set>
namespace esengine::resource {
+// =============================================================================
+// Include Expansion
+// =============================================================================
+
+namespace {
+
+constexpr u32 kMaxIncludeDepth = 16;
+
+std::string ltrim(const std::string& s) {
+ usize start = s.find_first_not_of(" \t");
+ return start == std::string::npos ? std::string() : s.substr(start);
+}
+
+bool expandIncludes(const std::string& source,
+ const ShaderIncludeResolver& resolver,
+ std::unordered_set<std::string>& active,
+ u32 depth,
+ std::string& out,
+ std::string& errorMessage) {
+ if (depth > kMaxIncludeDepth) {
+ errorMessage = "Shader include depth exceeded " + std::to_string(kMaxIncludeDepth);
+ return false;
+ }
+
+ std::istringstream stream(source);
+ std::string line;
+ while (std::getline(stream, line)) {
+ const std::string lead = ltrim(line);
+ if (lead.rfind("#include", 0) != 0) {
+ out += line;
+ out += '\n';
+ continue;
+ }
+
+ const usize q1 = lead.find('"');
+ const usize q2 = (q1 == std::string::npos) ? std::string::npos : lead.find('"', q1 + 1);
+ if (q1 == std::string::npos || q2 == std::string::npos || q2 <= q1 + 1) {
+ errorMessage = "Malformed #include directive: " + line;
+ return false;
+ }
+ const std::string path = lead.substr(q1 + 1, q2 - q1 - 1);
+
+ if (!resolver) {
+ errorMessage = "#include \"" + path + "\" used but no include resolver was provided";
+ return false;
+ }
+ if (active.count(path) != 0) {
+ errorMessage = "Circular #include of \"" + path + "\"";
+ return false;
+ }
+ std::optional<std::string> contents = resolver(path);
+ if (!contents) {
+ errorMessage = "Could not resolve #include \"" + path + "\"";
+ return false;
+ }
+
+ active.insert(path);
+ if (!expandIncludes(*contents, resolver, active, depth + 1, out, errorMessage)) {
+ return false;
+ }
+ active.erase(path);
+ }
+ return true;
+}
+
+} // namespace
+
// =============================================================================
// Parser State
// =============================================================================
@@ -34,6 +102,10 @@ enum class ParseState {
// =============================================================================
ParsedShader ShaderParser::parse(const std::string& source) {
+ return parse(source, ShaderIncludeResolver{});
+}
+
+ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeResolver& resolver) {
ParsedShader result;
result.valid = false;
@@ -42,7 +114,17 @@ ParsedShader ShaderParser::parse(const std::string& source) {
return result;
}
- std::istringstream stream(source);
+ std::string expanded;
+ {
+ std::unordered_set<std::string> active;
+ std::string includeError;
+ if (!expandIncludes(source, resolver, active, 0, expanded, includeError)) {
+ result.errorMessage = includeError;
+ return result;
+ }
+ }
+
+ std::istringstream stream(expanded);
std::string line;
ParseState state = ParseState::Global;
std::string currentVariantName;
diff --git a/src/esengine/resource/ShaderParser.hpp b/src/esengine/resource/ShaderParser.hpp
index 2ceab7be2..f49eca66a 100644
--- a/src/esengine/resource/ShaderParser.hpp
+++ b/src/esengine/resource/ShaderParser.hpp
@@ -18,12 +18,27 @@
#include "../core/Types.hpp"
+#include <functional>
+#include <optional>
#include <string>
#include <vector>
#include <unordered_map>
namespace esengine::resource {
+// =============================================================================
+// Include Resolver
+// =============================================================================
+
+/**
+ * @brief Resolves an #include path to its file contents.
+ *
+ * Return std::nullopt to signal "not found" — the parser will report a
+ * descriptive error. Resolvers are free to cache, normalize paths, or
+ * delegate to a virtual filesystem.
+ */
+using ShaderIncludeResolver = std::function<std::optional<std::string>(const std::string&)>;
+
// =============================================================================
// Shader Stage Enum
// =============================================================================
@@ -107,12 +122,21 @@ struct ParsedShader {
class ShaderParser {
public:
/**
- * @brief Parses shader source into structured format
+ * @brief Parses shader source into structured format (no include support)
* @param source The complete .esshader file content
* @return Parsed shader data with valid flag indicating success
*/
static ParsedShader parse(const std::string& source);
+ /**
+ * @brief Parses shader source with #include "path" expansion
+ * @param source The complete .esshader file content
+ * @param resolver Callback used to fetch included file contents
+ * @return Parsed shader data with valid flag indicating success
+ */
+ static ParsedShader parse(const std::string& source,
+ const ShaderIncludeResolver& resolver);
+
/**
* @brief Assembles final GLSL source for a specific stage
* @param parsed The parsed shader data
diff --git a/src/esengine/resource/loaders/ShaderLoader.cpp b/src/esengine/resource/loaders/ShaderLoader.cpp
index 9460c6e83..3ad33ae21 100644
--- a/src/esengine/resource/loaders/ShaderLoader.cpp
+++ b/src/esengine/resource/loaders/ShaderLoader.cpp
@@ -46,8 +46,28 @@ LoadResult<Shader> ShaderFileLoader::load(const LoadRequest& request) {
return LoadResult<Shader>::err("Failed to read shader file: " + request.path);
}
- auto result = loadFromSource(source, request.platform);
+ std::string shaderDir;
+ const usize slash = request.path.find_last_of("/\\");
+ if (slash != std::string::npos) {
+ shaderDir = request.path.substr(0, slash);
+ }
+
+ std::vector<std::string> includedPaths;
+ ShaderIncludeResolver resolver = [&shaderDir, &includedPaths](const std::string& include)
+ -> std::optional<std::string> {
+ std::string full = shaderDir.empty() ? include : shaderDir + "/" + include;
+ if (!FileSystem::fileExists(full)) return std::nullopt;
+ std::string contents = FileSystem::readTextFile(full);
+ if (contents.empty()) return std::nullopt;
+ includedPaths.push_back(std::move(full));
+ return contents;
+ };
+
+ auto result = loadFromSource(source, request.platform, resolver);
result.dependencies.push_back(request.path);
+ for (auto& dep : includedPaths) {
+ result.dependencies.push_back(std::move(dep));
+ }
if (result.isOk()) {
ES_LOG_DEBUG("ShaderFileLoader: Loaded shader from {}", request.path);
@@ -58,7 +78,13 @@ LoadResult<Shader> ShaderFileLoader::load(const LoadRequest& request) {
LoadResult<Shader> ShaderFileLoader::loadFromSource(const std::string& source,
const std::string& platform) {
- ParsedShader parsed = ShaderParser::parse(source);
+ return loadFromSource(source, platform, ShaderIncludeResolver{});
+}
+
+LoadResult<Shader> ShaderFileLoader::loadFromSource(const std::string& source,
+ const std::string& platform,
+ const ShaderIncludeResolver& resolver) {
+ ParsedShader parsed = ShaderParser::parse(source, resolver);
if (!parsed.valid) {
ES_LOG_ERROR("ShaderFileLoader: {}", parsed.errorMessage);
return LoadResult<Shader>::err("Shader parse error: " + parsed.errorMessage);
diff --git a/src/esengine/resource/loaders/ShaderLoader.hpp b/src/esengine/resource/loaders/ShaderLoader.hpp
index 4742396ba..eabd3f033 100644
--- a/src/esengine/resource/loaders/ShaderLoader.hpp
+++ b/src/esengine/resource/loaders/ShaderLoader.hpp
@@ -56,7 +56,7 @@ public:
const char* getTypeName() const override { return "Shader"; }
/**
- * @brief Loads a shader from source string
+ * @brief Loads a shader from source string (no include support)
* @param source Complete .esshader content
* @param platform Platform variant to use (empty for auto-detect)
* @return Load result with shader or error message
@@ -64,6 +64,17 @@ public:
LoadResult<Shader> loadFromSource(const std::string& source,
const std::string& platform = "");
+ /**
+ * @brief Loads a shader from source string, expanding #include via resolver
+ * @param source Complete .esshader content
+ * @param platform Platform variant to use (empty for auto-detect)
+ * @param resolver Callback invoked to fetch included files
+ * @return Load result with shader or error message
+ */
+ LoadResult<Shader> loadFromSource(const std::string& source,
+ const std::string& platform,
+ const ShaderIncludeResolver& resolver);
+
/**
* @brief Gets the default platform identifier for current build
* @return Platform string (e.g., "WEBGL", "DESKTOP")