wanp/townengine
2
1
Fork 0
Code Issues 6 Pull Requests Packages Projects Releases Wiki Activity

move /docs/interop.md to about-townengine.html

Browse Source
This commit is contained in:
veclavtalica 2025-02-20 15:42:05 +03:00
parent 3d51c8c48f
commit 0b89c90ad7
2 changed files with 28 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
docs/interop.md
View File

@ -1,19 +0,0 @@
# interoperability
api needs to facilitate easy interoperability with other languages and tools,
for that certain considerations are taken:
* number of public api calls is kept at the minimum
* procedure parameters can only use basic types, no aggregates, with exception of Vec/Matrix types and alike,
with no new additions, ever (see [/include/twn_types.h](../include/twn_types.h))
* enum types are allowed, as they decay to numeric type (but language-specific api can decide to provide simple ways to use them)
* optionals can be expressed via pointer passage of value primitives, assumed immutable, with the NULL expressing default value
* no opaque types, only keys if needed
* pointers to pointers aren't allowed
* when mutation on input is done, - it shouldn't be achieved by a mutable pointer, but the return value
* return value could be a simple aggregate that is translatable to a dictionary of primitives
* module prefix is used for namespacing, actual symbols come after the prefix (`<module>_<symbol>`)
* symbols should not contain numerics at the start nor after the namespace prefix
* 32 bit floating point is the only numeric type
* [/include/twn_api.json](../share/twn_api.json) file is hand-kept with a schema to aid automatic binding generation and tooling
* parameter names should not collide with keywords of any language that is targetted; if so happens, parameter alias could be added
* any procedure can't have more than 8 parameters

29
docs/wiki/about-townengine.html
View File

@ -38,12 +38,39 @@
<p><b>No-Versioning.</b> We don't stick to releases and "contract" obligations for things to remain stagnant.
It's fair to ask end user to put little effort if they need newer set of features, instead of putting all the burden on us.
You can always just stick to particular version you started the development of the project with,
{twn} doesn't need system wide installation.</blockquote>
{twn} doesn't need system wide installation.
<p><b>Bounded.</b> Most places assume runtime limits, to help with portability and growing out-of-hand complexity.
Frames cannot take more than sane allocated time, breaking off infinite loops.
<p><b>Toolable.</b> External editors are the way, with their own separate modes of being. Simple web socket interface will be defined for that.
</blockquote>
<p><a name="wiki"></a><strong>T1.2 </strong><strong>Wiki</strong>
<blockquote>
<p>Purpose of this wiki is to collect information on various usages of {twn} across the genres, FAQ style.
You're welcomed to contribute to it. It's written in HTML so basic you can edit it by hand.
Just check <a href="template.html">template.html</a>.
<p>Content is divided into chapters, where prefix specifies its category. Currently following prefixes are used:
<ul>
<li><b>T</b> for townengine; development and apis.
<li><b>G</b> for gamedev; guides and FAQs on game making.
</ul>
</blockquote>
<p><a name="abi"></a><strong>T1.3 </strong><strong>ABI</strong>
<blockquote>
<p>For native code ABI defines convention to ease tooling integration.
<ul>
<li>32 bit floating point is the only numeric type.
<li>Procedure parameters can only use basic types, with no aggregates. Exceptions are Vec, Rect and Color types.
(see /include/twn_types.h)
<li>Enum types are not allowed, as they decay to integer type, identity strings are used instead.
<li>No opaque nor pointer types allowed, use string keys if needed. Think of it as data base relations.
<li>Only null terminated string is allowed as a sequential type in both parameters and returns.
<li>Return value could be a simple aggregate that is translatable to a dictionary of primitives, without nesting.
<li>Symbols should not contain numerics. For example, sqrt2 must become square_root.
<li>/share/twn_api.json file is hand-kept with a schema to aid automatic binding generation and tooling.
<li>Parameter names should not collide with keywords of any language that is targeted; if so happens, parameter alias could be added.
Currently forbidden: <b>repeat</b>.
<li>Procedure can't have more than 8 parameters.
</ul>
</blockquote>
</body>
</html>