Mercurial > games > semicongine
annotate README.md @ 1499:1f58458b7ef7 default tip main
did: fix a few issues with tests
| author | sam <sam@basx.dev> |
|---|---|
| date | Tue, 14 Oct 2025 00:27:28 +0700 |
| parents | 768bf1a8407b |
| children |
| rev | line source |
|---|---|
| 922 | 1 Note: If you are reading this on Github, please not that this is only a mirror |
| 1266 | 2 repository and the newest code is hosted on my mercurial repository at |
| 3 https://hg.basx.dev/games/semicongine/. | |
| 922 | 4 |
| 289 | 5 # Semicongine |
| 41 | 6 |
|
926
f8974736e446
did: smile, just for the sake of testing mercurial hooks :)
sam <sam@basx.dev>
parents:
925
diff
changeset
|
7 Hi there |
| 8 | 8 |
|
213
b5d9410a8184
add: resource packaging and loading for different resource types, simplify build commands, update readme
Sam <sam@basx.dev>
parents:
202
diff
changeset
|
9 This is a little game engine, mainly trying to wrap around vulkan and the |
|
b5d9410a8184
add: resource packaging and loading for different resource types, simplify build commands, update readme
Sam <sam@basx.dev>
parents:
202
diff
changeset
|
10 operating system's windowing, input and audio system. I am using the last |
|
b5d9410a8184
add: resource packaging and loading for different resource types, simplify build commands, update readme
Sam <sam@basx.dev>
parents:
202
diff
changeset
|
11 programming language you will ever need, [Nim](https://nim-lang.org/) |
| 41 | 12 |
| 1301 | 13 The (incomplete, autogenerated) API documentation is hosted at <https://semicongine.diademgames.com/>. |
| 14 | |
| 1266 | 15 ## Features |
| 16 | |
| 17 The engine currently features the following: | |
| 18 | |
| 19 - No dependencies outside of this repo (except zip/unzip on Linux). All | |
| 1275 | 20 dependencies are included (`libs` for library dependencies, `tools` for |
| 21 binaries/scripts, `semicongine/thirdparty` for code dependencies) | |
| 1266 | 22 - Low-level, Vulkan-base rendering system |
| 1275 | 23 - All vertex/uniform/descriptors/shader-formats can and must be defined |
| 24 "freely". The only restriction that we currently have, is that vertex data is | |
| 25 non-interleaved. | |
| 1266 | 26 - A ton of compiletime checks to ensure the defined mesh-data and shaders are |
| 27 compatible for rendering | |
| 28 - Simple audio mixer, should suffice for most things | |
| 29 - Simple input-system, no controller support at this time | |
| 1275 | 30 - Resource packaging of images, audio and 3D files as either folders, zip files or embedded in the executable |
| 1267 | 31 - Simple font and text rendering |
| 1266 | 32 - A few additional utils like a simple storage API, a few algorithms for |
| 33 collision detection, noise generation and texture packing, and a simple | |
| 34 settings API with hot-reloading | |
| 35 | |
|
1367
0f3f2017b054
add: some reminders what we would like to do
sam <sam@basx.dev>
parents:
1302
diff
changeset
|
36 ## Wishlist |
|
0f3f2017b054
add: some reminders what we would like to do
sam <sam@basx.dev>
parents:
1302
diff
changeset
|
37 |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
38 - Macro-based internal DSL to convert Nim code into GLSL/slang at compile time |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
39 - Better memory management |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
40 - Simple buffer resizing |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
41 - Mechanism to mark unused buffers |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
42 - Use mapped GPU buffers without copying (implement seq with pointers to GPU memory) |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
43 - Do not keep copy of content for un-mapped buffers around (only pass data on creating or update) |
|
1367
0f3f2017b054
add: some reminders what we would like to do
sam <sam@basx.dev>
parents:
1302
diff
changeset
|
44 |
| 1266 | 45 ## Hello world example |
| 46 | |
| 47 Attention, this project is not optimized for "hello world"-scenarios, so you | |
| 1302 | 48 have to write quite a few lines to get something to display: |
| 1266 | 49 |
| 1269 | 50 ```nim |
| 1266 | 51 |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
52 import ../semicongine |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
53 import ../semicongine/rendering |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
54 import ../semicongine/input |
| 1266 | 55 |
| 56 # required | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
57 initEngine("Hello triangle") |
| 1266 | 58 |
| 59 # set up a simple render pass to render the displayed frame | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
60 var renderpass = createDirectPresentationRenderPass( |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
61 depthBuffer = false, samples = VK_SAMPLE_COUNT_1_BIT |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
62 ) |
| 1266 | 63 |
| 64 # the swapchain, needs to be attached to the main renderpass | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
65 setupSwapchain(renderpass = renderpass) |
| 1266 | 66 |
| 67 # render data is used for memory management on the GPU | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
68 var renderdata = initRenderData() |
| 1266 | 69 |
| 70 type | |
| 71 # define a push constant, to have something moving | |
| 72 PushConstant = object | |
| 73 scale: float32 | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
74 |
| 1266 | 75 # This is how we define shaders: the interface needs to be "typed" |
| 76 # but the shader code itself can freely be written in glsl | |
| 77 Shader = object | |
| 78 position {.VertexAttribute.}: Vec3f | |
| 79 color {.VertexAttribute.}: Vec3f | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
80 pushConstant {.PushConstant.}: PushConstant |
| 1266 | 81 fragmentColor {.Pass.}: Vec3f |
| 82 outColor {.ShaderOutput.}: Vec4f | |
| 83 # code | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
84 vertexCode: string = |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
85 """void main() { |
| 1266 | 86 fragmentColor = color; |
| 87 gl_Position = vec4(position * pushConstant.scale, 1);}""" | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
88 fragmentCode: string = |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
89 """void main() { |
| 1266 | 90 outColor = vec4(fragmentColor, 1);}""" |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
91 |
| 1266 | 92 # And we also need to define our Mesh, which does describe the vertex layout |
| 93 TriangleMesh = object | |
| 94 position: GPUArray[Vec3f, VertexBuffer] | |
| 95 color: GPUArray[Vec3f, VertexBuffer] | |
| 96 | |
| 97 # instantiate the mesh and fill with data | |
| 98 var mesh = TriangleMesh( | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
99 position: asGPUArray([vec3(-0.5, -0.5), vec3(0, 0.5), vec3(0.5, -0.5)], VertexBuffer), |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
100 color: asGPUArray([vec3(0, 0, 1), vec3(0, 1, 0), vec3(1, 0, 0)], VertexBuffer), |
| 1266 | 101 ) |
| 102 | |
| 103 # this allocates GPU data, uploads the data to the GPU and flushes any thing that is host-cached | |
| 104 # this is a shortcut version, more fine-grained control is possible | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
105 assignBuffers(renderdata, mesh) |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
106 renderdata.flushAllMemory() |
| 1266 | 107 |
| 108 # Now we need to instantiate the shader as a pipeline object that is attached to a renderpass | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
109 var pipeline = createPipeline(Shader(), renderPass = renderPass) |
| 1266 | 110 |
| 111 # the main render-loop will exit if we get a kill-signal from the OS | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
112 while updateInputs(): |
| 1266 | 113 # starts the drawing for the next frame and provides us necesseary framebuffer and commandbuffer objects in this scope |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
114 withNextFrame(framebuffer, commandbuffer): |
| 1266 | 115 # start the main (and only) renderpass we have, needs to know the target framebuffer and a commandbuffer |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
116 withRenderPass( |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
117 renderPass, |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
118 framebuffer, |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
119 commandbuffer, |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
120 frameWidth(), |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
121 frameHeight(), |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
122 vec4(0, 0, 0, 0), |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
123 ): |
| 1266 | 124 # now activate our shader-pipeline |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
125 withPipeline(commandbuffer, pipeline): |
| 1266 | 126 # and finally, draw the mesh and set a single parameter |
| 127 # more complicated setups with descriptors/uniforms are of course possible | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
128 renderWithPushConstant( |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
129 commandbuffer = commandbuffer, |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
130 pipeline = pipeline, |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
131 mesh = mesh, |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
132 pushConstant = PushConstant(scale: 0.3), |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
133 ) |
| 1266 | 134 |
| 135 # cleanup | |
|
1443
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
136 checkVkResult vkDeviceWaitIdle(engine().vulkan.device) |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
137 destroyPipeline(pipeline) |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
138 destroyRenderData(renderdata) |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
139 destroyRenderPass(renderpass) |
|
768bf1a8407b
add: hello-triangle example, did: update according readme parts
sam <sam@basx.dev>
parents:
1367
diff
changeset
|
140 destroyVulkan() |
| 1266 | 141 |
| 142 ``` | |
| 143 | |
| 1275 | 144 ## Future development |
| 41 | 145 |
| 1266 | 146 For now all features that I need are implemented. I will gradually add more |
| 147 stuff that I need, based on the games that I am developing. Here are a few | |
| 148 things that I consider integrating at a later point, once I have gather some | |
| 149 more experience what can/should be used across different projects: | |
|
194
93f661a20f74
did: a bit of cleanup with the config, also add some documentation
Sam <sam@basx.dev>
parents:
187
diff
changeset
|
150 |
| 1269 | 151 - [ ] More support for glTF format (JPEG textures, animations, morphing) |
| 1275 | 152 - [ ] Some often used utils like camera-controllers, offscreen-rendering, shadow-map rendering, etc. |
| 153 - [ ] Some UI-stuff | |
| 1269 | 154 - [ ] Controller support |