Refactoring Shader Workflow in Axmol v3

[halx99]

Proposal: Refactoring Shader Workflow in Axmol v3

Hello Axmol community,

As we approach Axmol v3 beta1, the original roadmap focused on completing the physics 2D/3D refactor. However, we are now considering prioritizing a shader workflow refactor before beta1 release.

Motivation

• Current GLSL-based workflow requires axslcc and deep patches to spirv-cross to support layout(sampler_slot=xx) for D3D12.
• This approach increases maintenance cost and complicates compatibility across multiple RHIs.

Proposed Change

• Switch to HLSL as the unified front-end shader language.
• Use DXC to compile HLSL → SPIR-V, then leverage spirv-cross for GLSL/MSL output.
• Define Axmol-specific semantics (e.g., AX_PSIZE/PSIZE) to ensure consistent mapping across D3D, Vulkan, Metal, and OpenGL.
• No need for custom sampler_slot syntax — HLSL natively supports resource binding via register(t#), register(s#), register(b#), etc.
• Reduce or eliminate deep patches to spirv-cross, lowering long-term maintenance burden.

Expected Benefits

• Cleaner, more maintainable shader workflow.
• Better alignment with D3D/Metal semantics.
• Unified handling of features like PSIZE and sampler slots across RHIs.
• Easier onboarding for contributors familiar with HLSL/DXC.

Community Feedback

We’ll keep this discussion open for two weeks to gather feedback.

Thank you for your input and continued support!

[rh101]

If we do move forward with HLSL, then it would be extremely helpful if examples of the conversion process of existing Axmol GLSL shaders to their HLSL equivalents is documented in one location, such as in a wiki article. It can be used as a reference to help developers convert their own custom GLSL shaders to HLSL.

[solan-solan]

It's hard to believe the customers would want to convert their own custom GLSL shaders to HLSL. Maybe they will do this in new projects.

[rh101]

Version 3 of Axmol is a major release of the engine, so breaking changes are expected. Not allowing for such changes, by keeping things as they are, can have a overall negative impact. The project needs to allow for improvements, in terms of new features, functionality, and to reduce the maintenance burden where possible. The major release of a project is the most suitable time for such things to be implemented.

This proposal is one of those improvements, and while I understand the reluctance of developers to have to do some extra work to port to a new major release, it is not an unreasonable expectation for such a release. If not, then there is always v2 of Axmol, which is a solid and proven version of the engine, and no-one is forcing developers to move to v3.

[solan-solan]

There is distinguish between v2/v3 with engine api and now shaders. It is not simple to move from one to another sometimes later when v3 become stable with existing custom code for new supposed projects.
Looks like the fate of cocos wates v2 in future.
Since that i think it was normal to try v3 now if you desire to use axmol.

[rh101]

Backwards compatibility is not always a good reason to prevent significant improvements to the engine, and it tends to carry forward legacy code that requires additional time and resources to maintain. Again, a major version of any product is the chance to improve things, so why not let that be the case to make things better.

Also, true, Axmol v2 will not last forever, but at the same time, that cannot be expected of any product. For now, it is working, and it should be for quite a while yet.