Compare commits

...

109 commits

Author SHA1 Message Date
John Alanbrook 8bab8b258f add imgui direct draw functions 2024-09-14 23:42:46 -05:00
John Alanbrook a3f68316ca upgrade imgui to 1.91.1, sokol to sept 10 2024 2024-09-14 12:15:08 -05:00
John Alanbrook 640c8389f3 attempt at sequencer 2024-09-14 09:36:40 -05:00
John Alanbrook 79c5e7f3a4 add imnodes and neo sequencer 2024-09-13 17:56:02 -05:00
John Alanbrook 2a8dae2bf6 add then to entities 2024-09-13 14:34:54 -05:00
John Alanbrook 01905a26a2 add layers to callbacks 2024-09-13 10:28:44 -05:00
John Alanbrook ad6b82ded1 add imgui drag n drop 2024-09-12 23:17:09 -05:00
John Alanbrook 41c76e1a70 add render image string capability 2024-09-11 12:25:42 -05:00
John Alanbrook e3029994f9 add color to sprite ssbo 2024-09-10 14:33:49 -05:00
John Alanbrook 0d5ce8f62c fix particles 2024-09-09 18:55:07 -05:00
John Alanbrook 8da89f1032 add imgui popups 2024-09-08 11:24:21 -05:00
John Alanbrook a1cd43bcfd fix sounds; add imgui 2024-09-07 15:14:03 -05:00
John Alanbrook 188c55a8e0 fix text issue 2024-09-07 00:11:34 -05:00
John Alanbrook ec5e9249f0 text fixing 2024-09-06 22:47:04 -05:00
John Alanbrook 67fe729d8c fix double input bug 2024-09-06 18:51:09 -05:00
John Alanbrook af79dba48a add imgui int input 2024-09-06 10:52:00 -05:00
John Alanbrook fd8b1b8006 fix uickjs string print issue 2024-09-04 14:34:45 -05:00
John Alanbrook 6d2696437c add imgui listbox 2024-09-04 13:23:20 -05:00
John Alanbrook d33c1af92c vector imgui 2024-09-04 07:41:48 -05:00
John Alanbrook 5ddf3558ef unsure 2024-09-03 14:08:46 -05:00
John Alanbrook 99bd0091f9 fix input down 2024-09-01 16:16:35 -05:00
John Alanbrook ef0a59f489 fix entity delete error 2024-09-01 13:59:34 -05:00
John Alanbrook 794e581336 add imgui text box; fix image blit 2024-08-31 00:38:26 -05:00
John Alanbrook 1305a762e9 add imgui collapsing header 2024-08-30 18:22:53 -05:00
John Alanbrook dc59f0642c fix image finding 2024-08-30 14:17:37 -05:00
John Alanbrook 2c1f34177b add entity start on play 2024-08-29 16:55:01 -05:00
John Alanbrook dc25e23aa8 add optional pivot for vector.rotate 2024-08-29 10:20:22 -05:00
John Alanbrook bc313d6f8c add more imgui functions 2024-08-28 16:38:31 -05:00
John Alanbrook fce8ff6081 remove spam logging 2024-08-28 13:49:24 -05:00
John Alanbrook 603d9a5406 not sure 2024-08-27 20:56:45 -05:00
John Alanbrook 6c6593c3d9 fix gizmo drawing 2024-08-27 14:58:08 -05:00
John Alanbrook 31a47b5b7d add easy hashify function 2024-08-27 13:57:38 -05:00
John Alanbrook 2ad2d18af7 add cheat menu 2024-08-26 11:13:26 -05:00
John Alanbrook 8abb0ae10f fix imgui input handle capture 2024-08-25 17:42:43 -05:00
John Alanbrook 88de7fb547 add console switcher 2024-08-25 15:29:35 -05:00
John Alanbrook 94d4d86944 fix particle render bug 2024-08-25 14:23:22 -05:00
John Alanbrook 76497fb600 add music audio bus 2024-08-25 06:35:04 -05:00
John Alanbrook 05aeb62242 add more imgui functions 2024-08-25 00:18:30 -05:00
John Alanbrook 9fd958f414 add alternate output term path 2024-08-24 18:46:21 -05:00
John Alanbrook 39cbd92bfb fix polygon rendering bug 2024-08-24 18:40:29 -05:00
John Alanbrook ed7d65523a fix resource finding 2024-08-24 08:04:41 -05:00
John Alanbrook 27fa286625 add optional end function call to tweens 2024-08-23 14:17:51 -05:00
John Alanbrook b589a742cf add y sort option 2024-08-22 14:43:04 -05:00
John Alanbrook b31069fe91 animated gifs correctly hotsync 2024-08-22 14:41:01 -05:00
John Alanbrook 285a227691 fix camera view calculation 2024-08-22 13:31:00 -05:00
John Alanbrook 5690ee7fba add profiling and testing 2024-08-20 02:17:56 -05:00
John Alanbrook 05acefd683 fix gui.cpp 2024-08-19 07:47:27 -05:00
John Alanbrook 849c85cd7a imgui window stuff 2024-08-15 12:26:37 -05:00
John Alanbrook daad058225 image hotreload 2024-08-12 15:19:34 -05:00
John Alanbrook a29ce7e8d0 skeleton animation 2024-08-10 04:06:44 -05:00
John Alanbrook f5a89915eb model skinning 2024-08-09 14:39:31 -05:00
John Alanbrook 57c2285019 clean up 3d model creation 2024-08-08 17:32:58 -05:00
John Alanbrook ceccd032c2 add colors; add repl check 2024-08-08 13:25:47 -05:00
John Alanbrook 515eb65b22 shader hotreload; better circle shader; add nogame for setup help; fix io.mod; add joystick input; fix entity hotreload; implement array length in C; add default game.size 2024-08-07 16:55:08 -05:00
John Alanbrook a28230a647 rudimentary hot reload for actors 2024-08-06 16:05:24 -05:00
John Alanbrook 432d8200f3 add memory profiling tooling 2024-08-06 14:23:21 -05:00
John Alanbrook ceb728b1a7 memory output 2024-08-05 15:26:18 -05:00
John Alanbrook 33d4ebf14a make profiling togglable 2024-08-04 15:20:11 -05:00
John Alanbrook 570c12e3db Add many C based math and statistic functions 2024-08-02 21:52:50 -04:00
John Alanbrook 05bc965d10 update quickjs 2024-07-25 22:07:22 -05:00
John Alanbrook 1142bfb896 made engine into a small bootstrap script 2024-07-25 17:53:53 -05:00
John Alanbrook 6047452b62 speed up string functions 2024-07-25 16:14:37 -05:00
John Alanbrook 0a7f5a5cdd add sprite sort 2024-07-25 10:33:51 -05:00
John Alanbrook 55ae7e2171 remove spurious profiling lines 2024-07-25 08:38:10 -05:00
John Alanbrook cb6f64925e add profiling 2024-07-24 14:17:32 -05:00
John Alanbrook 90940b42f5 add quickjs cpu profiling 2024-07-24 08:26:29 -05:00
John Alanbrook ef802bb6f2 add sprite and rendering to engine js 2024-07-23 17:21:27 -05:00
John Alanbrook 08725d474d add transform cache mat4 2024-07-23 14:30:41 -05:00
John Alanbrook f905dbc571 batch drawing for debug shapes 2024-07-23 12:02:46 -05:00
John Alanbrook 531cc1b43e particle emitters store and reuse particles 2024-07-23 08:40:20 -05:00
John Alanbrook 9d51858266 sprite ssbo batch render 2024-07-22 19:07:02 -05:00
John Alanbrook d4b057dc6f javascript based particle system 2024-07-22 15:40:58 -05:00
John Alanbrook ff71ee9db6 particle texture 2024-07-22 08:29:31 -05:00
John Alanbrook 2eb75491ea particle system support 2024-07-21 15:03:43 -05:00
John Alanbrook cf6feffda2 custom ssbo buffers 2024-07-18 17:09:35 -05:00
John Alanbrook 066b213fbe particle ssbo 2024-07-18 12:39:58 -05:00
John Alanbrook 63239fa51a mum image fix 2024-07-16 20:34:09 -05:00
John Alanbrook 845ee6ade3 mum fixes; add mum.rectangle 2024-07-16 15:37:07 -05:00
John Alanbrook fb88641883 mum work 2024-07-15 15:54:18 -05:00
John Alanbrook 2f8827fd78 mum work 2024-07-14 16:09:50 -05:00
John Alanbrook 805c9298e6 fix input down 2024-07-11 16:37:24 -05:00
John Alanbrook bb5e6b883a rendering improvements 2024-07-11 14:25:45 -05:00
John Alanbrook acb0fcdcd9 debug drawing for mum 2024-07-10 09:39:28 -05:00
John Alanbrook 9626da4ff8 add background image and slice 2024-07-09 16:43:09 -05:00
John Alanbrook d36ac1957f fix 9 slice 2024-07-09 13:48:15 -05:00
John Alanbrook 9a98ce5e43 New mum tools 2024-07-09 01:03:39 -05:00
John Alanbrook dfec02ebcb correct gitignore and add prosperon image 2024-07-03 16:41:38 -05:00
John Alanbrook e6450b8981 add api 2024-07-03 16:38:29 -05:00
John Alanbrook fa83aabd5f Move doc to docs; fix colors 2024-07-03 08:29:09 -05:00
John Alanbrook aa3de462da add mkdocs requirements 2024-07-02 16:27:07 -05:00
John Alanbrook 50386c0e04 Merge branch 'master' into imgui
# Conflicts:
#	scripts/std.js
#	source/engine/jsffi.c
2024-07-02 16:21:22 -05:00
John Alanbrook 3949b33855 mkdocs 2024-07-02 16:14:32 -05:00
John Alanbrook e1ac2a8fe3 fix render image 2024-07-01 17:00:01 -05:00
John Alanbrook b25cd85071 more gui 2024-07-01 13:05:26 -05:00
John Alanbrook f7fdae024d remove unneede info logging 2024-07-01 10:59:31 -05:00
John Alanbrook 829b6386da some array fns 2024-06-26 16:57:17 -05:00
John Alanbrook 42db19d748 add alpha to all colors 2024-06-26 13:12:34 -05:00
John Alanbrook b5e655e1f2 add vector angle 2024-06-25 17:53:15 -05:00
John Alanbrook 7e851756de fix sprite render 2024-06-19 18:52:41 -05:00
John Alanbrook 35deec52ae image generation 2024-06-19 11:45:34 -05:00
John Alanbrook ebfa801560 add check to image blit 2024-06-18 17:10:24 -05:00
John Alanbrook 2fe4e825aa add thumbnail making 2024-06-18 16:14:23 -05:00
John Alanbrook 1b5bd399cd now read off individual file times from packed gamefiles 2024-06-07 10:38:21 -05:00
John Alanbrook 131bfda5f8 Add debug drawing to 2d physics 2024-06-07 09:49:13 -05:00
John Alanbrook 9d90cd6f56 Fix cache detection for shaders 2024-06-07 00:43:15 -05:00
John Alanbrook b2a466ce8b add box point generation 2024-06-07 00:39:37 -05:00
John Alanbrook ecf3859067 initial add of imgui 2024-06-05 16:07:44 -05:00
John Alanbrook 32484ac4a0 If command not found, play game 2024-04-26 17:06:43 -05:00
John Alanbrook 5da74796d5 Remove sgscale references 2024-04-22 08:47:04 -05:00
220 changed files with 111994 additions and 3834 deletions

3
.gitignore vendored
View file

@ -24,9 +24,6 @@ jsc
.DS_Store
*.html
.vscode
primum*
Prosperon*
prosperon*
*.icns
game.zip
icon.ico

View file

@ -15,7 +15,9 @@ OPT ?= 0
LD = $(CC)
STEAM = steam/sdk
STEAMAPI =
STEAMAPI =
LDFLAGS += -lstdc++
ifeq ($(CROSS)$(CC), emcc)
LDFLAGS += --shell-file shell.html --closure 1
@ -73,7 +75,7 @@ else
CPPFLAGS += -O2
endif
CPPFLAGS += -DHAVE_CEIL -DCP_USE_CGTYPES=0 -DCP_USE_DOUBLES=0 -DHAVE_FLOOR -DHAVE_FMOD -DHAVE_LRINT -DHAVE_LRINTF $(includeflag) $(WARNING_FLAGS) -I. -DVER=\"$(SEM)\" -DCOM=\"$(COM)\" -DINFO=\"$(INFO)\" #-DENABLE_SINC_MEDIUM_CONVERTER -DENABLE_SINC_FAST_CONVERTER -DCP_COLLISION_TYPE_TYPE=uintptr_t -DCP_BITMASK_TYPE=uintptr_t
CPPFLAGS += -DHAVE_CEIL -DCP_USE_CGTYPES=0 -DCP_USE_DOUBLES=0 -DHAVE_FLOOR -DHAVE_FMOD -DHAVE_LRINT -DHAVE_LRINTF $(includeflag) $(WARNING_FLAGS) -I. -DVER=\"$(SEM)\" -DCOM=\"$(COM)\" -DDATE=\"$(DATE)\" -DINFO=\"$(INFO)\" -Wno-narrowing #-DENABLE_SINC_MEDIUM_CONVERTER -DENABLE_SINC_FAST_CONVERTER -DCP_COLLISION_TYPE_TYPE=uintptr_t -DCP_BITMASK_TYPE=uintptr_t
CPPFLAGS += -DCONFIG_VERSION=\"2024-02-14\" -DCONFIG_BIGNUM #for quickjs
# ENABLE_SINC_[BEST|FAST|MEDIUM]_CONVERTER
@ -148,7 +150,7 @@ OBJS := $(patsubst %.m, %$(INFO).o, $(OBJS))
engineincs != find source/engine -maxdepth 1 -type d
includeflag != find source -type d -name include
includeflag += $(engineincs) source/engine/thirdparty/sokol source/engine/thirdparty/stb source/engine/thirdparty/cgltf source/engine/thirdparty/TinySoundFont source/engine/thirdparty/dr_libs
includeflag += $(engineincs) source/engine/thirdparty/sokol source/engine/thirdparty/stb source/engine/thirdparty/cgltf source/engine/thirdparty/TinySoundFont source/engine/thirdparty/dr_libs source/engine/thirdparty/imgui
includeflag += $(STEAM)/public
includeflag += source
includeflag := $(addprefix -I, $(includeflag))
@ -164,6 +166,7 @@ APP = prosperon
NAME = $(APP)$(INFO)$(EXT)
SEM != git describe --tags --abbrev=0
COM != git rev-parse --short HEAD
DATE != date +%s
LDLIBS += $(STEAMAPI)
LDLIBS := $(addprefix -l, $(LDLIBS))
@ -198,6 +201,9 @@ endif
all: $(NAME)
cp -f $(NAME) $(APP)$(EXT)
$(APP): $(NAME)
cp -f $(NAME) $(APP)
$(NAME): $(OBJS) $(DEPS)
@echo Linking $(NAME)
$(CROSS)$(LD) $^ $(CPPFLAGS) $(LDFLAGS) -L. $(LDPATHS) $(LDLIBS) -o $@
@ -265,7 +271,7 @@ crossmac: Prosperon.icns
cp Prosperon.icns Prosperon.app/Contents/Resources
crosswin:
make CROSS=x86_64-w64-mingw32ucrt- OS=Windows_NT CC=gcc
make CROSS=x86_64-w64-mingw32- OS=Windows_NT CC=gcc
crossweb:
make CC=emcc OS=wasm
@ -280,6 +286,9 @@ clean:
docs: doc/prosperon.org
make -C doc
mv doc/html .
api: $(APP)
./prosperon run 'for (var i in globalThis) say(i)' | xargs -I {} ./prosperon api {} > docs/api/{}.md
TAGINC != find . -name "*.[chj]"
tags: $(TAGINC)

View file

@ -1,10 +0,0 @@
console.stdout_lvl = 4;
say(`config after std`);
window.size = [600,600];
window.rendersize = [200,200];
say(`config after window size`);
globalThis.gamestate = {};
gamestate.grid = 10;
//window.title = "Accio!";
say(`end of config`);

View file

@ -1,5 +0,0 @@
html: prosperon.org
emacs prosperon.org -f org-html-export-to-html --kill
mv prosperon.html index.html
mkdir html
cp index.html orb.gif dos.ttf org-info.js style.css prosperon_orb_horizontal.gif html

View file

@ -1,525 +0,0 @@
#+title: Prosperon Documentation
#+author: John Alanbrook
#+options: html-postamble:nil
#+DESCRIPTION: Prosperon documentation
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css" />
#+HTML_HEAD: <script defer data-domain="prosperon.dev" data-api="https://net.pockle.world/net/event" src="https://net.pockle.world/bat/script.js"></script>
#+HTML_HEAD: <link rel="icon" href="orb.gif" type="image/gif">
#+INFOJS_OPT: view:showall ltoc:above path:org-info.js toc:nil
@@html:
<script src="https://kit.fontawesome.com/a87f68ad0a.js" crossorigin="anonymous"></script>
<nav class="floathead">
<a href="https://prosperon.dev">
<img height=50px src="prosperon_orb_horizontal.gif">
</a>
<a href=#top><i class="fa-solid fa-bars"></i></a>
<a href="https://github.com/johnalanbrook/prosperon"><i class="fa-brands fa-github"></i></a>
<a href="https://x.com/pockleworld"><i class="fa-brands fa-x-twitter"></i></a>
</nav>
@@
* Getting Started
#+begin_scholium
Press 'i' to see the table of contents.
Press '?' for shortcuts on navigating this document!
#+end_scholium
** Installation
*** Linux & MacOS
Install the most [[https://prosperon.dev/download][recent binaries]] into your ~$PATH~.
*** Windows
Copy the executable into any folder and run it. If no game is deteced, it scaffolds for you.
*** Building
You will need ~sokol-shdc~ in the top of your directory. Then, ~make shaders~ and ~make~. The command ~make install~ copies it to your home's ~.bin~ path.
** Playing your first game
Download any of the completed example projects. Run ~prosperon play~ in the folder.
Poke around the example projects. You will find it refreshingly straight forward.
* Engine Tour
Prosperon is built in a code-first fashion.
** Scripting
The scripting language used in Prosperon is Javascript, with QuickJS. It is [[https://tc39.es/ecma262/2023/][ES2023]] compliant. It is fast, and has a number of features that make it well suited for a video game engine, like ref counting. Read more about it [[https://bellard.org/quickjs/][here]].
#+begin_scholium
Javascript is used here mostly to set up objects and tear them down. Although computationally expensive tasks can be done using QuickJS, Prosperon makes it easy to extend with raw C.
#+end_scholium
*** How Prosperon games are structured
Prosperon schews the CommonJS and ES module systems for a custom one suitable for a computer game actor model. It is more restricted than either system, while retaining their full power.
Prosperon games are structured into two types of source files:
- scripts
- actors
Scripts end with a return statement. A script can return a function, an object of functions, or any other sort of value.
#+begin_scholium
It is a common requirement to add some amount of functionality to an object. It can be easily done with a script file.
#+begin_src
*script.js*
function hello() { say("hello"); };
return hello;
#+end_src
#+begin_src
var o = {};
o.use("hello.js");
o.hello();
#+end_src
The ~use~ function on any object loads a module, and ~assign~s its return to the object.
#+end_scholium
Scripts are loaded into memory only once. Further ~use~ statements only generate references to the statements. Because *scripts* are executed in a lambda environment, any ~var~ declared inside the script files are effectively private variables, persistent variables.
In a *script*, ~this~ refers to ~undefined~. It is nothng.
In an *actor* source file, ~this~ refers to the actor. Actors do not end in a ~return~ statement. *actor* source is intended to set up a new agent in your game. Set up the new entity by loading modules and assigning functions to ~this~.
*** Script entry points
The first way you can customize Prosperon is by adding scripts to the folder you're running it from. Any file ending with *.js* is a *script* which can be ran by Prosperon.
| script | When called |
|-----------------+---------------------------------------------|
| config.js | First script on Prosperon load |
| game.js | Entry point for running the game |
| editorconfig.js | Entry point for running the editor |
| predbg.js | Called before running debug |
| debug.js | Debug set up |
| dbgret.js | After stopping debug mode, used for cleanup |
#+begin_scholium
Try it out. Add a script called ~config.js~ to your folder, with this.
#+begin_src
console.log("Hello world!");
Game.quit();
#+end_src
Run ~prosperon~. You will see "Hello world!" in the console, and it shuts down.
#+end_scholium
Using ~config.js~ and ~game.js~, you can write an entire game, without reaching any further. When you want to populate a world with independent actors, entities are what you will reach for.
** Actors
The fundamental tool for building in Prosperon is the actor system. Actors run independently from each other. Actors are defined by a combination of code and data. All actors have a *master* which controls certain properties of the actor.
The most masterful actor is the *Empyrean*. The first actor you create will have the Empyrean as its master. Subsequent actors can use any other actor as its master.
| fn | description |
|---------------------+----------------------------------------------------------|
| spawn(text, config) | Creates an actor as the padawan of this one, using text |
| kill() | Kills an actor |
| delay(fn, seconds) | Calls 'fn' after 'seconds' with the context of the actor |
*** Actor Lifetime
When an actor dies, all of the actors that have it as their master will die as well.
*** Turns
Actors get fragments of time called a *turn*. Actors which belong to different systems can have different lengths of turns.
*** Actor files
Actor files end with the extension *.jso*[fn::"Javascript object".]. They list a series of functions to call on a newly formed actor. Actors have a number of useful functions which are called as defined.
| function | call time |
|----------+----------------------------------------------------------|
| start | The first function called when the actor is in the world |
| update | Called once per turn |
| gui | Called on GUI draw |
| stop | Called when the actor is killed |
| gizmo | Called by the editor when the entity is selected |
#+begin_scholium
Create a new actor, then kill it.
#+begin_src
var act_die_call = function() {
console.log(`Actor ${this.id} has died.`);
}
var act1 = Empyrean.spawn();
var act2 = actor1.spawn();
act1.stop = act_die_call;
act2.stop = act_die_call;
Empyrean.kill(); /* Error: The Empyrean cannot be killed */
act1.kill();
act2.kill(); /* Error: act2 has been killed because act1 was */
#+end_src
#+end_scholium
#+begin_scholium
Now simplify by putting the code into a file named *hello.jso*.
#+begin_src
this.stop = function() {
console.log(`Actor ${this.id} has died.`);
}
#+end_src
Now spawn two actors using it.
#+begin_src
var act1 = Empyrean.spawn("hello.jso");
var act2 = act1.spawn("hello.jso");
#+end_src
#+end_scholium
*** Actor configuration
Actors can be created using an optional configuration file. A configuration file is one of any accepted data types. Currently, JSON or [[https://www.crockford.com/nota.html][Nota]]. Configuration files are loaded after an actor's script file, overwriting any defined values on it.
#+begin_scholium
Add a name for the actor to take on using a configuration file named *hello.json*.
#+begin_src
{
"name": "Actor 1"
}
#+end_src
Now create *hello.jso* to use it.
#+begin_src
this.start = function() { console.log(`I, ${this.name}, have been created.`); }
#+end_src
#+end_scholium
** Entities
Game worlds are made of entities. Entities are a type of actor with a number of useful properties. Entities can only be created on the actor named *Primum*[fn::See the Primum Mobile]. The Primum is the outermost actor with a physical space. While Actors are more abstract, Entities exist in a definite space, with a position, rotation, and so on. Entities can respond to physics and play sounds. Anything which can be thought of as having a position in space should be an entitiy.
#+begin_scholium
The first and most masterful entity is the Primum. The Primum has no components, and its rotation and position are zero. It defines the center of the game.
#+end_scholium
In editor mode, when an entity moves, all of its *padawans* also move.
When the game is actively simulating, this only holds if there are physical constraints between them.
Prosperon automatically generates physical pin constraints between objects with the appropriate physical properties.
*** Adding Components
Entities can have *components*. Components are essentially javascript wrappers over C code into the engine. Scripting is done to set the components up on entities, after which most of the work is done by the C plugin.
#+begin_scholium
For example, to render an image, set up a *sprite* component on an entity and point its path to an image on your harddrive.
#+begin_src
var ent = Empyrean.spawn();
var spr = ent.add_component(component.sprite);
spr.path = "image.png";
#+end_src
Put that into your config file and run ~prosperon~. You should see the contents of "image.png" on the screen.
Try using an animated gif. Prosperon has native support for gif animations!
#+end_scholium
Components only work in the context of an entity. They have no meaning outside of a physical object in the world. They have no inherent scripting capabilities.
While components can be added via scripting, it is easier to add them via the editor, as we will later see.
*** Ur system
The ur[fn::A German prefix meaning primitive, original, or earliest.] system is a prototypical inheritence system used by the actor files. When actor files are loaded, they are stored as an ur. An *ur* holds a list of (text, config) required to create an entity.
When prosperon starts, it searches for urs by name. Any file ending in ".jso" or ".json" will be interpereted as an ur, with same named jso and json being applied as (text, config) for an ur. A jso or json alone also constitute an ur.
An ur can also be defined by a json file. If an ur is found, it takes predecent over auto generated urs. The json of an ur looks like this:
| field | description |
|----|----|
| text | Path to a script file, or array of script files, to apply to the object |
| data | Path to a json file, or array of json files, to apply to the object |
Any ur file with this sort of json creates an ur which can be created in the game. A file named "box.ur" will be ingested and be available as "ur.box". When saving differences, it creates a json file with the same name as an ur (in this case, "box.json").
#+begin_scholium
Create an ur from the *hello* files above, and then spawn it.
#+begin_src
ur.create("hello", "hello.jso", "hello.json");
Primum.spawn(ur.hello);
#+end_src
When creating an actor from source files, all of its setup must take place. In this example, the setup happens during *ur.create*, and spawning is simply a matter of prototyping it.
#+end_scholium
This method allows high composability of game objects.
If an entity is created without an ur, is ur is defined as its given text and data. It cannot be saved. It must be given a new ur name.
Objects can be composed on the fly by stringing together urs. For example, a "2x.json" might define scale as 2x. Then, you can create a goblin with `ur.goblin`, or a large goblin with `ur.goblin.2x`. This creates a goblin object, and then applies the 2x scripts and jsons onto the object.
*** Urs in game
Each ur has the following fields.
| field | description |
|-----------+-------------------------------------------------------------|
| instances | An array of instances of this ur |
| name | Name of the ur |
| text | Path to the script file |
| data | Object to write to a newly generated actor |
| proto | An object that looks like a freshly made entity from the ur |
An *ur* has a full path given like ~ur.goblin.big~. ~goblin~ and ~big~ can both possibly have a *.jso* script as well as a *data* file.
When ~goblin.big~ is created, the new object has the ~goblin~ script run on it, followed by the ~big~ script. The ~data~ fields consist of objects prototyped from each other, so that the ~__proto__~ of ~big.data~ is ~goblin.data~. All fields of this objects are assigned to the ~big goblin~.
The unaltered form of every ur-based-entity is saved in the ur's ~proto~ field. As you edit objects, the differences between how your object is now, compared to its ~ur.proto~ is a list of differences. These differences can be rolled into the ~ur~, or saved as a subtype.
*** Prototyping Entities
Ur types are the prototype of created entities. This makes it trivial to change huge swathes of the game, or make tiny adjustments to single objects, in a natural and intuitive way. When a value is changed on an entity, it is private. When a value is changed on an ur, it propogates to all entities. Values cannot be added or removed in subtypes.
Entities all have the following functions to assist with this:
| function | use |
|---------------+---------------------------------------------|
| clone(parent) | Create an entity prototyped from the parent |
| dup(parent) | Create an exact duplicate of the parent |
| revert() | Removes all local changes on the entity |
Speaking of practical experience, is best for ur prototype chains to be shallow.
*** Spawning
Actor data and ur types can remember which entities were contained in it when saving. They are stored in the *objects* field. When an entity with an *objects* field is spawned, it spawns all of the objects listed in turn.
When an entity is spawned, it is addressable directly through its master entity. Its name is generated from its file or ur type name.
#+begin_scholium
Let's take a simple RPG game.
#+begin_src
Primum
level1
orc
goblin
human
sword
ui
#+end_src
The orc, for example, is addressable by ~Primum.level1.orc~. The ~human~ has a ~sword~ spawned underneath it. When he is killed, his sword also disappears.
#+end_scholium
*** Resources
Assets can generally be used simply with their filename. Assets can be modified with a sidecar file named *filename.asset*, so, a file ~ball.png~ can have additional parameters through its ~ball.png.asset~ file.
| sigil | meaning |
|--------+------------------------|
| \slash | root of project |
| @ | root of save directory |
| # | root of link |
Resources can be referenced in a relative manner by actor scripts. When it comes to actors using assets, relative filepaths are useful and encouraged.
#+begin_src
/
score.wav
/bumper
hit.wav
bumper.jso
/ball
hit.wav
ball.jso
#+end_src
Path resolution occurs during actor creation. In effect, a reference to *hit.wav* in *bumper.jso* will resolve to the absolute path */bumper/hit.wav*.
If the asset is not found, it is searched for until the project root is reached. The bumper can reference *score.wav* and have the path resolution take place. Later, if the it is decided for the bumper to have a unique score sound, a new /score.wav/ can be placed in its folder and it will work without changing any code.
#+begin_scholium
Caution! Because the path is resolved during object load, you will need to fresh the bumper's ur or spawn a new bumper for it to use the newly placed /score.wav/.
#+end_scholium
**** Links
Links can be specified using the "#" sign. These are shortcuts you can specify for large projects. Specify them in the array ~Resources.links~.
An example is of the form ~trees:/world/assets/nature/trees~. Links are called with ~#~, so you can now make a "fern" with ~Primum.spawn("#trees/fern.jso")~.
*** Ur auto creation
Instead of coding all the ur type creation by hand, Prosperon can automatically search your project's folder and create the ur types for you. Any /[name].jso/ file is converted into an ur with the name. Any /[name].json/ file is then applied over it, should it exist. If there is a /.json/ file without a corresponding /.jso/, it can still be turned into an ur, if it is a valid ur format.
Folders and files beginning with a '.' (hidden) or a '_' will be ignored for ur creation.
The folder hierarchy of your file system determines the ur prototype chain. /.jso/ files inside of a folder will be subtyped off the folder ur name.
Only one ur of any name can be created.
#+begin_src
@/
flipper.js
flipper/
left.js
@/
flipper/
flipper.js
left/
left.js
#+end_src
~prototypes.generate_ur(path)~ will generate all ur-types for a given path. You can preload specific levels this way, or the entire game using ~prototypes.generate_ur('.')~. If your game is small enough, this can have a massive runtime improvement.
** Input
Input is done in a highly generic and customizable manner. *players* can take control of any object (actor or otherwise) in Prosperon, after which it is referred to as a *pawn* of a player. If the object has a defined *input* object, it is a valid pawn. One player can have many pawns, but each pawn may have only one player.
Pawns are added as a stack, with the newest ones getting priority, and handled first. It is possible for pawns to block input to lower pawns on the stack.
#+begin_src
/newest/
car <== When a key is pressed, this is the first pawn to handle input
player
ui <== /block/ is set to true here, so editor recieves no input!
editor
/oldest/
#+end_src
The default player can be obtained with ~Player.players[0]~. Players are all local, and the highest number is determined by platform.
The *input* object defines a number of keys or actions, with their values being functions.
*** Editor input
The editor input style defines keystrokes. It is good for custom editors, or any sort of game that requires many hotkeys. Keystrokes are case sensitive and can be augmented with auxiliary keys.
| symbol | key |
|--------+-------|
| C | ctrl |
| M | alt |
| S | super |
#+begin_src
var orc = Primum.spawn(ur.orc);
orc.inputs = {};
orc.inputs.a = function() { ... };
orc.inputs.A = function() { ... }; /* This is only called with a capital A! */
orc.inputs['C-a'] = function() { ... }; /* Control-a */
Player.players[0].control(orc); /* player 0 is now in control of the orc */
#+end_src
The input object can be modified to customize how it handles input.
| property | type | effect |
|----------------+----------+--------------------------------------|
| post | function | called after any input is processed |
| =release_post= | function | called after any input is released |
| fallthru | bool | false if input should stop with this |
| block | bool | true if input should stop with this |
The input can be modified by setting properties on the associated function.
| property | type | effect |
|----------+----------+--------------------------------------------------------|
| released | function | Called when the input is released |
| rep | bool | true if holding the input should repeatedly trigger it |
| down | function | called while the input is down |
** GUI
Game GUIs are written by registering an entity's *gui* property to a function.
The GUI system which ships with Prosperon is called *MUM*. MUM is a declarative, immediate mode interface system. Immediate to eliminate the issue of data synchronization in the game.
All GUI objects derive from MUM. MUM has a list of properties, used for rendering. Mum also has functions which cause drawing to appear on the screen.
** Physics
Prospeorn comes with the [[https://chipmunk-physics.net][Chipmunk]] physics engine built in. It is a fast, stable physics solution. All entities are assumed to be physics based objects, and components can be added to them to enable more physics features.
* Editor Tour
Prosperon's visual editor is an assistant for the creation and editing of your game entities and actors. In the editor, all ur types are loaded, and assets are constantly monitored for changes for hot reloading.
To initiate it, execute ~prosperon~.
** Editing entities
The desktop is the topmost entity that exists in the editor. Instead of editing specific files, you simply load them into your desktop, and go from there. This makes it easier to see two different entities simultaneously so you can ensure changes to one are congruous with the vision for the others.
The main editor view is made up of entities. Each entity can have a number of components attached to it. When an entity is selected, its name, position, and list of components are listed.
Basic use of the editor involves spawning new entities, or ones from already made ur types, editing them, and then saving them as new ur types or overwriting the ones they spawned from. Specific tools have been written to make editing components and levels easier than with a text editor, and the editor is easily extendable for your own purposes.
Assign the entity's *gizmo* property to a function to have that function called each gui rendering frame.
** The REPL[fn::Read-eval-print loop]
The REPL lets you poke around in the game. It makes iteration and experimentation fast, fun, and easy.
The symbol ~$~ references the current REPL entity. If no entity is selected, the REPL entity is the currently edited one. Otherwise, it is the selected entity, or group of entities, as an array.
#+begin_scholium
Easily run commands on multiple entities using Javascript functions like for each.
#+begin_src
$.forEach(e => console.log(e.pos));
#+end_src
#+end_scholium
The REPL is a powerful tool for editing your game. Arbitrary code can be ran in it, meaning any esoteric activity you need done for your game can be done easily. Commonly used functions should be copied into your /editorconfig.js/ to be called and used at will.
** Playing the game
Playing the game involves running the game from a special /debug.js/ file, or from the beginning, as if the game were packaged and shipped.
| key | action |
|-------+-----------------------------------------------------|
| f5 | Play the game, starting with entry point /debug.js/ |
| f6 | Play the game from the beginning |
While playing the game, a limited editor is available that allows for simple debugging tasks.
| key | action |
|-----+-----------------------------|
| C-p | Pause |
| M-p | One time step |
| C-q | Quit play, return to editor |
** Script Editor
Prosperon comes with an in-engine script editor. It implements a subset of emacs, and adds a few engine specific features.
*** Syntax coloring? ... nope!
The editor that ships with Prosperon has *context coloring*, which is a good deal more useful than syntax coloring.
** Debugging
Debugging functions are mapped to the F buttons, and are available in any debug build of the game. Pressing the specified key toggles the feature; pressing it with /alt/ shows a legend for that feature.
| key | description |
|-----+----------------------------|
| F1 | Draw physics info |
| F3 | Draw bounding boxes |
| F12 | Draw gui info |
* Exporting your game
Prosperon is a multiplatform engine. Bundling your game for these platforms essentially involves three steps:
- Baking static content
- Conversion of assets
- Packing into a CDB[fn::Constant database]
To distribute your game for a given platform, run ~prosperon build {platform}~.
| platform |
|----------|
| Linux |
| MacOS |
| Windows |
You will find your game ready to go. Rename the executable to the name of your game and run it to play. Congratulations!
** Building static content
Static content creation involves any number of optimizations.
- Bitmap font creation
- Texture map creation
Creation of these assets is invisible. Prosperon updates its understanding of how to pull assets based on the existance of these packed ones.
** Converting assets
Images, videos, and sounds, are converted to assets most suitable for the target platform. This may be for speed or simple compatability. *You do not need to do anything*. Use your preferred asset types during production.
** Packing into a CDB
A *cdb* is known as a "constant database". It is a write once type of database, with extremely fast retrieval times. Packing your game into a cdb means to create a database with key:value pairs of the filenames of your game. The Prosperon executable is already packed with a core cdb. Your game assets are packed alongside it as the game cdb.
You can create your game's cdb by running ~prosperon -b~. You will find a *game.cdb* in the root directory.
* Modding & Patching
When an asset is requested in Prosperon, it is searched for in the following manner.
1. The cwd[fn::current working directory]
2. The game cdb (not necessarily present)
3. The core cdb
Game modification is trivial using this described system. By putting an asset in the same path as the asset's location in the game cdb, when that asset is requested it will be pulled from the file system instead of the game cdb.
Given a Prosperon-built game, you can unpack its content into a directory by running ~prosperon unpack {game}~.
** Shipping
Once a game's assets are modified, it may be desirable to ship them. Run ~prosperon patch create {game}~ to create a /patch.cdb/ filled only with the files that are different compared to those found in the /game.cdb/ in the /game/.
To update /game/ to use the new patch, run ~prosperon patch apply {patch}~, replacing /patch/ with the name of the cdb file generated above.
Many patches can be bundled by running ~prosperon patch bundle {list of patches}~. This creates a patch that will update the game as if the user had updated each patch in order.
Mods can be distributed with the same idea.

29
docs/api/Cmdline.md Normal file
View file

@ -0,0 +1,29 @@
# Cmdline
#### cmds
**array**
[
{
"flag": "l",
"doc": "Set log level."
}
]
#### orders
**object**
#### register_cmd(flag, fn, doc)
#### register_order(order, fn, doc, usage = "")
#### print_order(fn)

140
docs/api/Color.md Normal file
View file

@ -0,0 +1,140 @@
# Color
#### white
**array**
[
1,
1,
1,
1
]
#### black
**array**
[
0,
0,
0,
1
]
#### blue
**array**
[
0.32941176470588235,
0.43137254901960786,
1,
1
]
#### green
**array**
[
0.47058823529411764,
1,
0.0392156862745098,
1
]
#### yellow
**array**
[
0.984313725490196,
1,
0.16862745098039217,
1
]
#### red
**array**
[
1,
0.1411764705882353,
0.0784313725490196,
1
]
#### teal
**array**
[
0.3764705882352941,
0.9882352941176471,
0.9294117647058824,
1
]
#### gray
**array**
[
0.7098039215686275,
0.7098039215686275,
0.7098039215686275,
1
]
#### cyan
**array**
[
0,
1,
1,
1
]
#### purple
**array**
[
0.6352941176470588,
0.36470588235294116,
0.8901960784313725,
1
]
#### editor
**object**
#### tohtml(v)
#### Arkanoid
**object**
#### Gameboy
**object**
#### Apple
**object**
#### Debug
**object**
#### Editor
**object**
#### normalize(c)

35
docs/api/ColorMap.md Normal file
View file

@ -0,0 +1,35 @@
# ColorMap
#### makemap(map)
#### Jet
**object**
[object Object]
#### BlueRed
**object**
[object Object]
#### Inferno
**object**
[object Object]
#### Bathymetry
**object**
[object Object]
#### Viridis
**object**
[object Object]
#### sample(t, map = this)
Sample a given colormap at the given percentage (0 to 1).

58
docs/api/Ease.md Normal file
View file

@ -0,0 +1,58 @@
# Ease
#### linear(t)
#### in(t)
#### out(t)
#### inout(t)
#### quad
**object**
#### cubic
**object**
#### quart
**object**
#### quint
**object**
#### expo
**object**
#### bounce
**object**
#### sine
**object**
#### elastic
**object**

23
docs/api/Event.md Normal file
View file

@ -0,0 +1,23 @@
# Event
#### events
**object**
#### observe(name, obj, fn)
#### unobserve(name, obj)
#### rm_obj(obj)
#### notify(name, ...args)

6
docs/api/Gizmos.md Normal file
View file

@ -0,0 +1,6 @@
# Gizmos
#### pick_gameobject_points(worldpos, gameobject, points)

173
docs/api/Mum.md Normal file
View file

@ -0,0 +1,173 @@
# Mum
#### padding
**array**
[
0,
0
]
#### offset
**array**
[
0,
0
]
#### font
**string**
#### selectable
**boolean**
#### selected
**boolean**
#### font_size
**number**
#### text_align
**string**
#### scale
**number**
#### angle
**number**
#### anchor
**array**
[
0,
1
]
#### hovered
**object**
#### text_shadow
**object**
#### text_outline
**number**
#### color
**array**
[
1,
1,
1,
1
]
#### margin
**array**
[
0,
0
]
#### width
**number**
#### height
**number**
#### max_width
**number**
#### max_height
**number**
#### image_repeat
**boolean**
#### image_repeat_offset
**array**
[
0,
0
]
#### debug
**boolean**
#### make(def)
#### prestart()
#### start()
#### extend(def)
#### text(def)
#### button(def)
#### window(def)
#### image(def)
#### column(def)
#### debug_colors
**object**

56
docs/api/Register.md Normal file
View file

@ -0,0 +1,56 @@
# Register
#### registries
**array**
[
{},
{
"doc": "Called once per frame."
},
{},
{},
{},
{},
{}
]
#### add_cb(name)
#### appupdate
**object**
#### update
**object**
Called once per frame.
#### physupdate
**object**
#### gui
**object**
#### debug
**object**
#### draw
**object**
#### screengui
**object**

78
docs/api/Resources.md Normal file
View file

@ -0,0 +1,78 @@
# Resources
#### replpath(str, path)
#### replstrs(path)
#### scripts
**array**
[
"jsoc",
"jsc",
"jso",
"js"
]
#### images
**array**
[
"png",
"gif",
"jpg",
"jpeg"
]
#### sounds
**array**
[
"wav",
"flac",
"mp3",
"qoa"
]
#### is_image(path)
#### find_image(file)
#### find_sound(file)
#### find_script(file)
#### is_sound(path)
#### is_animation(path)
#### is_path(str)
#### texture
**object**
#### gif
**object**

67
docs/api/Spline.md Normal file
View file

@ -0,0 +1,67 @@
# Spline
#### sample_angle(type, points, angle)
#### bezier_loop(cp)
#### bezier_node_count(cp)
#### is_bezier(t)
#### is_catmull(t)
#### bezier2catmull(b)
#### catmull2bezier(c)
Given a set of control points C for a camtull-rom type curve, return a set of cubic bezier points to give the same curve.
#### catmull_loop(cp)
#### catmull_caps(cp)
Given a set of control points cp, return the necessary caps added to the spline.
#### type
**object**
#### bezier_tan_partner(points, i)
#### bezier_cp_mirror(points, i)
#### bezier_point_handles(points, i)
#### bezier_nodes(points)
#### bezier_is_node(points, i)
#### bezier_is_handle(points, i)

27
docs/api/SpriteAnim.md Normal file
View file

@ -0,0 +1,27 @@
# SpriteAnim
Functions to create Primum animations from varying sources.
#### make(path)
#### gif(path)
Convert a gif.
#### strip(path, frames, time=0.05)
Given a path and number of frames, converts a horizontal strip animation, where each cell is the same width.
#### aseprite(path)
Given an aseprite json metadata, returns an object of animations defined in the aseprite file.
#### validate(anim)
#### find(path)
Given a path, find the relevant animation for the file.

15
docs/api/Tween.md Normal file
View file

@ -0,0 +1,15 @@
# Tween
#### default
**object**
#### start(obj, target, tvals, options)
#### make(obj, target, tvals, options)

46
docs/api/Vector.md Normal file
View file

@ -0,0 +1,46 @@
# Vector
#### length(v)
#### norm(v)
#### project(a, b)
#### dot(a, b)
#### random()
#### angle_between(a,b)
#### angle(v)
#### rotate(v,angle)
#### equal(v1, v2, tol)
#### reflect(vec, plane)
#### reflect_point(vec, point)

34
docs/api/actor.md Normal file
View file

@ -0,0 +1,34 @@
# actor
#### spawn(script, config, callback)
Create a new actor, using this actor as the master, initializing it with 'script' and with data (as a JSON or Nota file) from 'config'.
#### rm_pawn(pawn)
#### timers
**array**
[]
#### kill()
Remove this actor and all its padawans from existence.
#### interval(fn, seconds)
#### delay(fn, seconds)
Call 'fn' after 'seconds' with 'this' set to the actor.
#### padawans
**array**
[
{}
]

22
docs/api/ai.md Normal file
View file

@ -0,0 +1,22 @@
# ai
#### race(list)
#### sequence(list)
#### parallel(list)
#### dofor(secs, fn)
#### wait(secs = 1)

2
docs/api/allsprites.md Normal file
View file

@ -0,0 +1,2 @@
# allsprites

6
docs/api/app.md Normal file
View file

@ -0,0 +1,6 @@
# app
#### die()

1
docs/api/assert.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:11] warn, script: Cannot print the API of something that isn't an object.

17
docs/api/audio.md Normal file
View file

@ -0,0 +1,17 @@
# audio
#### channels
**number**
#### buffer_frames
**number**
#### samplerate
**number**

46
docs/api/bbox.md Normal file
View file

@ -0,0 +1,46 @@
# bbox
#### overlap(box1, box2)
#### fromcwh(c, wh)
#### frompoints(points)
#### topoints(bb)
#### tocwh(bb)
#### towh(bb)
#### pointin(bb, p)
#### move(bb, pos)
#### expand(oldbb, x)
#### blwh(bl,wh)
Bounding box from (bottom left, width height)
#### fromobjs(objs)

View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:11] warn, script: Cannot print the API of something that isn't an object.

1
docs/api/cmd_args.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:11] warn, script: Cannot print the API of something that isn't an object.

22
docs/api/component.md Normal file
View file

@ -0,0 +1,22 @@
# component
#### sprite(obj)
#### edge2d(obj)
#### circle2d(obj)
#### poly2d(obj)
#### seg2d(obj)

68
docs/api/console.md Normal file
View file

@ -0,0 +1,68 @@
# console
#### print()
#### rec()
#### stdout_lvl
**number**
#### transcript
**string**
#### say(msg)
Write raw text to console, plus a newline.
#### log(msg)
#### pprint(msg, lvl = 0)
#### spam(msg)
#### debug(msg)
#### info(msg)
Output info level message.
#### warn(msg)
Output warn level message.
#### error(msg)
Output error level message, and print stacktrace.
#### panic(msg)
#### stackstr(skip = 0)
#### stack(skip = 0)
Output a stacktrace to console.
#### trace(skip = 0)

14
docs/api/convert.md Normal file
View file

@ -0,0 +1,14 @@
# convert
#### romanize(num)
#### deromanize(str)
#### buf2hex(buffer)

View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:11] warn, script: Cannot print the API of something that isn't an object.

50
docs/api/debug.md Normal file
View file

@ -0,0 +1,50 @@
# debug
#### fn_break(fn,obj = globalThis)
#### draw_phys
**boolean**
#### draw_bb
**boolean**
#### draw_gizmos
**boolean**
#### draw_names
**boolean**
#### draw()
#### inputs
**object**
#### gif
**object**
#### api
**object**
#### log
**object**

1
docs/api/deep_copy.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:11] warn, script: Cannot print the API of something that isn't an object.

74
docs/api/dspsound.md Normal file
View file

@ -0,0 +1,74 @@
# dspsound
#### noise()
#### pink()
#### red()
#### pitchshift()
#### noise_gate()
#### limiter()
#### compressor()
#### crush()
#### lpf()
#### hpf()
#### delay()
#### fwd_delay()
#### source()
#### mix()
#### master()
#### plugin_node()
#### midi()
#### mod()

1
docs/api/eachobj.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:10] warn, script: Cannot print the API of something that isn't an object.

1
docs/api/ediff.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:11] warn, script: Cannot print the API of something that isn't an object.

33
docs/api/editor.md Normal file
View file

@ -0,0 +1,33 @@
script:0: [2024-07-03 12:05:54] error, script: ReferenceError :: 'editor' is not defined
at <eval> (<input>)
at <anonymous> (scripts/debug.js:193)
at <anonymous> (scripts/std.js:385)
at cmd_args (scripts/std.js:458)
at <eval> (C eval)
Initializing cpSpace - Chipmunk v7.0.3 (Debug Enabled)
Compile with -DNDEBUG defined to disable debug mode and runtime assertion checks
USE REPORT
scripts/base.js 5.142 ms
scripts/render.js 1.197 ms
scripts/debug.js 521.4 us
scripts/input.js 1.055 ms
scripts/std.js 1.175 ms
scripts/diff.js 194.4 us
scripts/color.js 856.8 us
scripts/gui.js 597.1 us
scripts/tween.js 516.6 us
scripts/ai.js 128.0 us
scripts/physics.js 94.48 us
scripts/geometry.js 189.4 us
scripts/spline.js 253.1 us
scripts/components.js 1.761 ms
scripts/actor.js 185.2 us
scripts/entity.js 2.157 ms
scripts/widget.js 444.3 us
scripts/mum.js 76.63 us
scripts/editor.js 16.03 ms
ENTITY REPORT
scripts/engine.js:501: [2024-07-03 12:05:56] info, script: QUITTING

33
docs/api/entity.md Normal file
View file

@ -0,0 +1,33 @@
script:0: [2024-07-03 12:13:12] error, script: TypeError :: cannot read property 'doc' of undefined
at <anonymous> (scripts/debug.js:179)
at <anonymous> (scripts/debug.js:223)
at <anonymous> (scripts/std.js:385)
at cmd_args (scripts/std.js:458)
at <eval> (C eval)
Initializing cpSpace - Chipmunk v7.0.3 (Debug Enabled)
Compile with -DNDEBUG defined to disable debug mode and runtime assertion checks
USE REPORT
scripts/base.js 5.200 ms
scripts/render.js 1.284 ms
scripts/debug.js 516.9 us
scripts/input.js 970.4 us
scripts/std.js 1.103 ms
scripts/diff.js 230.1 us
scripts/color.js 1.148 ms
scripts/gui.js 665.1 us
scripts/tween.js 498.5 us
scripts/ai.js 125.5 us
scripts/physics.js 93.55 us
scripts/geometry.js 212.2 us
scripts/spline.js 252.9 us
scripts/components.js 1.780 ms
scripts/actor.js 188.5 us
scripts/entity.js 2.101 ms
scripts/widget.js 452.2 us
scripts/mum.js 70.77 us
scripts/editor.js 17.66 ms
ENTITY REPORT
scripts/engine.js:501: [2024-07-03 12:13:13] info, script: QUITTING

2
docs/api/entityreport.md Normal file
View file

@ -0,0 +1,2 @@
# entityreport

12
docs/api/esc.md Normal file
View file

@ -0,0 +1,12 @@
# esc
Functions and constants for ANSI escape sequences.
#### reset
**string**
#### color(v)

1
docs/api/find_ext.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:10] warn, script: Cannot print the API of something that isn't an object.

1
docs/api/fps.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:11] warn, script: Cannot print the API of something that isn't an object.

1
docs/api/frame_t.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:10] warn, script: Cannot print the API of something that isn't an object.

1
docs/api/frames.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:10] warn, script: Cannot print the API of something that isn't an object.

58
docs/api/game.md Normal file
View file

@ -0,0 +1,58 @@
# game
#### engine_start(s)
#### startengine
**number**
#### timescale
**number**
#### all_objects(fn, startobj = world)
#### find_object(fn, startobj = world)
#### tags
**object**
#### tag_add(tag, obj)
#### tag_rm(tag, obj)
#### tag_clear_guid(guid)
#### objects_with_tag(tag)
#### texture(path, force = false)
#### loadurs()
#### ur
**object**

1
docs/api/gen_notify.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:14] warn, script: Cannot print the API of something that isn't an object.

1
docs/api/gggstart.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:10] warn, script: Cannot print the API of something that isn't an object.

39
docs/api/gui.md Normal file
View file

@ -0,0 +1,39 @@
# gui
#### scissor()
#### text()
#### font_set()
#### scissor_win()
#### input_lmouse_pressed()
#### input_s_pressed()
#### input_w_pressed()
#### input_enter_pressed()
#### controls
**object**

75
docs/api/input.md Normal file
View file

@ -0,0 +1,75 @@
# input
#### show_keyboard()
#### keyboard_shown()
#### mouse_mode()
#### mouse_cursor()
#### cursor_img()
#### keycodes
**object**
#### codekeys
**object**
#### mouse
**object**
[object Object]
#### keyboard
**object**
#### state2str(state)
#### print_pawn_kbm(pawn)
#### procdown()
#### print_md_kbm(pawn)
#### has_bind(pawn, bind)
#### action
**object**
#### tabcomplete(val, list)
#### do_uncontrol(pawn)

108
docs/api/inputpanel.md Normal file
View file

@ -0,0 +1,108 @@
# inputpanel
#### title
**string**
#### value
**string**
#### on
**boolean**
#### pos
**array**
[
20,
460
]
#### wh
**array**
[
100,
100
]
#### anchor
**array**
[
0,
1
]
#### padding
**array**
[
5,
-15
]
#### gui()
#### guibody()
#### open()
#### start()
#### close()
#### action()
#### closeonsubmit
**boolean**
#### submit()
#### submit_check()
#### keycb()
#### caret
**number**
#### reset_value()
#### input_backspace_pressrep()
#### inputs
**object**

84
docs/api/io.md Normal file
View file

@ -0,0 +1,84 @@
# io
Functions for filesystem input/output commands.
#### exists()
Returns true if a file exists.
#### ls()
List contents of the game directory.
#### cp(f1,f2)
Copy file f1 to f2.
#### mv()
Rename file f1 to f2.
#### rm(f)
Remove file f.
#### chdir()
#### mkdir()
Make dir.
#### chmod(file,mode)
#### slurp(path)
Returns the contents of given file as a string.
#### slurpbytes(path)
Return the contents of a file as a byte array.
#### slurpwrite(path, c)
Write a given string to a given file.
#### save_qoa()
#### pack_start()
#### pack_add()
#### pack_end()
#### mod()
#### dumpfolder
**string**
#### mkpath(dir)
#### extensions(ext)
#### glob(pat)
Glob files in game directory.

42
docs/api/joint.md Normal file
View file

@ -0,0 +1,42 @@
# joint
#### pin()
#### pivot()
#### gear()
#### rotary()
#### damped_rotary()
#### damped_spring()
#### groove()
#### slide()
#### ratchet()
#### motor()

15
docs/api/json.md Normal file
View file

@ -0,0 +1,15 @@
# json
json implementation.
#### encode(value, replacer, space = 1)
Encode a value to json.
#### decode(text, reviver)
Decode a json string to a value.
#### readout(obj)
Encode an object fully, including function definitions.

33
docs/api/listpanel.md Normal file
View file

@ -0,0 +1,33 @@
# listpanel
#### assets
**array**
[]
#### allassets
**array**
[]
#### mumlist
**object**
#### submit_check()
#### start()
#### keycb()
#### guibody()

173
docs/api/mum.md Normal file
View file

@ -0,0 +1,173 @@
# Mum
#### padding
**array**
[
0,
0
]
#### offset
**array**
[
0,
0
]
#### font
**string**
#### selectable
**boolean**
#### selected
**boolean**
#### font_size
**number**
#### text_align
**string**
#### scale
**number**
#### angle
**number**
#### anchor
**array**
[
0,
1
]
#### hovered
**object**
#### text_shadow
**object**
#### text_outline
**number**
#### color
**array**
[
1,
1,
1,
1
]
#### margin
**array**
[
0,
0
]
#### width
**number**
#### height
**number**
#### max_width
**number**
#### max_height
**number**
#### image_repeat
**boolean**
#### image_repeat_offset
**array**
[
0,
0
]
#### debug
**boolean**
#### make(def)
#### prestart()
#### start()
#### extend(def)
#### text(def)
#### button(def)
#### window(def)
#### image(def)
#### column(def)
#### debug_colors
**object**

10
docs/api/nota.md Normal file
View file

@ -0,0 +1,10 @@
# nota
#### encode()
#### decode()

20
docs/api/notifypanel.md Normal file
View file

@ -0,0 +1,20 @@
# notifypanel
#### title
**string**
#### msg
**string**
#### action()
#### guibody()

149
docs/api/os.md Normal file
View file

@ -0,0 +1,149 @@
# os
#### cwd()
Get the absolute path of the current working directory.
#### env()
Return the value of the environment variable v.
#### sys()
#### system()
#### quit()
#### exit()
#### reindex_static()
#### gc()
#### eval()
#### make_body()
#### make_circle2d()
#### make_poly2d()
#### make_seg2d()
#### make_texture()
#### make_tex_data()
#### make_font()
#### make_model()
#### make_transform()
#### make_emitter()
#### make_buffer()
#### make_line_prim()
#### make_cylinder()
#### make_cone()
#### make_disk()
#### make_torus()
#### make_sphere()
#### make_klein_bottle()
#### make_trefoil_knot()
#### make_hemisphere()
#### make_plane()
#### make_video()
#### platform
**string**
#### user
**string**
#### home
**string**
#### prefpath()
#### openurl(url)

34
docs/api/performance.md Normal file
View file

@ -0,0 +1,34 @@
# performance
#### barecall()
#### unpack_num()
#### unpack_array()
#### pack_num()
#### pack_string()
#### unpack_string()
#### unpack_32farr()
#### call_fn_n()

33
docs/api/physics.md Normal file
View file

@ -0,0 +1,33 @@
at <anonymous> (scripts/engine.js:198)
at <eval> (C eval)
at get iterations (native)
at <anonymous> (scripts/debug.js:185)
at <anonymous> (scripts/debug.js:223)
at <anonymous> (scripts/std.js:385)
at cmd_args (scripts/std.js:458)
at <eval> (C eval)
USE REPORT
scripts/base.js 5.646 ms
scripts/render.js 1.282 ms
scripts/debug.js 598.0 us
scripts/input.js 1.005 ms
scripts/std.js 1.606 ms
scripts/diff.js 214.2 us
scripts/color.js 989.1 us
scripts/gui.js 931.0 us
scripts/tween.js 631.2 us
scripts/ai.js 130.4 us
scripts/physics.js 100.2 us
scripts/geometry.js 186.1 us
scripts/spline.js 286.5 us
scripts/components.js 2.147 ms
scripts/actor.js 236.0 us
scripts/entity.js 2.627 ms
scripts/widget.js 496.0 us
scripts/mum.js 75.69 us
scripts/editor.js 18.19 ms
ENTITY REPORT
scripts/engine.js:501: [2024-07-03 12:13:09] info, script: QUITTING

1
docs/api/physlag.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:195: [2024-07-03 12:13:10] warn, script: Cannot print the API of 'physlag', as it was not found.

68
docs/api/player.md Normal file
View file

@ -0,0 +1,68 @@
# player
#### 0
**object**
[object Object]
#### 1
**object**
[object Object]
#### 2
**object**
[object Object]
#### 3
**object**
[object Object]
#### players
**array**
A list of current players.
#### input(fn, ...args)
#### mouse_input(type, ...args)
#### char_input(c)
#### raw_input(cmd, state, ...args)
#### obj_controlled(obj)
#### print_pawns()
Print out a list of the current pawn control stack.
#### create()
#### pawns
**array**
[]
#### control(pawn)
Control a provided object, if the object has an 'inputs' object.
#### uncontrol(pawn)
Uncontrol a previously controlled object.

33
docs/api/poly2d.md Normal file
View file

@ -0,0 +1,33 @@
at <anonymous> (scripts/engine.js:198)
at <eval> (C eval)
at get radius (native)
at <anonymous> (scripts/debug.js:185)
at <anonymous> (scripts/debug.js:223)
at <anonymous> (scripts/std.js:385)
at cmd_args (scripts/std.js:458)
at <eval> (C eval)
USE REPORT
scripts/base.js 5.789 ms
scripts/render.js 2.126 ms
scripts/debug.js 709.5 us
scripts/input.js 1.222 ms
scripts/std.js 1.344 ms
scripts/diff.js 233.6 us
scripts/color.js 1.017 ms
scripts/gui.js 747.8 us
scripts/tween.js 625.2 us
scripts/ai.js 173.2 us
scripts/physics.js 124.2 us
scripts/geometry.js 221.7 us
scripts/spline.js 321.3 us
scripts/components.js 2.191 ms
scripts/actor.js 230.6 us
scripts/entity.js 4.996 ms
scripts/widget.js 607.5 us
scripts/mum.js 94.18 us
scripts/editor.js 22.40 ms
ENTITY REPORT
scripts/engine.js:501: [2024-07-03 12:13:09] info, script: QUITTING

1
docs/api/print.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:11] warn, script: Cannot print the API of something that isn't an object.

1
docs/api/process.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:10] warn, script: Cannot print the API of something that isn't an object.

136
docs/api/profcache.md Normal file
View file

@ -0,0 +1,136 @@
# profcache
#### scripts/base.js
**array**
[
5509269
]
#### scripts/render.js
**array**
[
1371390
]
#### scripts/debug.js
**array**
[
590951
]
#### scripts/input.js
**array**
[
1101579
]
#### scripts/std.js
**array**
[
1516994
]
#### scripts/diff.js
**array**
[
242594
]
#### scripts/color.js
**array**
[
1054188
]
#### scripts/gui.js
**array**
[
706472
]
#### scripts/tween.js
**array**
[
518110
]
#### scripts/ai.js
**array**
[
129610
]
#### scripts/physics.js
**array**
[
168777,
32773
]
#### scripts/geometry.js
**array**
[
216535
]
#### scripts/spline.js
**array**
[
284937
]
#### scripts/components.js
**array**
[
1904302
]
#### scripts/actor.js
**array**
[
196303
]
#### scripts/entity.js
**array**
[
2293362
]
#### scripts/widget.js
**array**
[
524872
]
#### scripts/mum.js
**array**
[
81892
]
#### scripts/editor.js
**array**
[
17107128
]

34
docs/api/profile.md Normal file
View file

@ -0,0 +1,34 @@
# profile
#### now()
#### best_t(t)
#### report(start, msg = "[undefined report]")
#### addreport(cache, line, start)
#### printreport(cache, name)
#### cpu(fn, times = 1, q = "unnamed")
#### ms(t)
#### secs(t)

138
docs/api/prosperon.md Normal file
View file

@ -0,0 +1,138 @@
# prosperon
#### phys2d_step()
#### window_render()
#### guid()
#### version
**string**
#### revision
**string**
#### semver
**object**
Functions for semantic versioning numbers. Semantic versioning is given as a triple digit number, as MAJOR.MINOR.PATCH.
#### iconified(icon)
#### focus(focus)
#### resize(dimensions)
#### suspended(sus)
#### mouseenter()
#### mouseleave()
#### touchpress(touches)
#### touchrelease(touches)
#### touchmove(touches)
#### clipboardpaste(str)
#### quit()
#### keys
**array**
[]
#### keydown(key, repeat)
#### keyup(key)
#### droppedfile(path)
#### textinput(c)
#### mousemove(pos, dx)
#### mousescroll(dx)
#### mousedown(b)
#### mouseup(b)
#### appupdate(...args)
#### update(...args)
#### physupdate(...args)
#### gui(...args)
#### debug(...args)
#### draw(...args)
#### screengui(...args)

189
docs/api/render.md Normal file
View file

@ -0,0 +1,189 @@
# render
Draw shapes in screen space.
#### flushtext()
#### camera_screen2world()
#### viewport()
#### end_pass()
#### commit()
#### glue_pass()
#### text_size()
#### text_ssbo()
#### set_camera()
#### pipeline()
#### setuniv3()
#### setuniv()
#### spdraw()
#### setuniproj()
#### setuniview()
#### setunivp()
#### setunim4()
#### setuniv2()
#### setuniv4()
#### setpipeline()
#### screencolor()
#### imgui_new()
#### gfx_gui()
#### imgui_end()
#### imgui_init()
#### poly_prim(verts)
#### make_shader(shader)
#### shader_apply_material(shader, material = {})
#### sg_bind(shader, mesh = {}, material = {}, ssbo)
#### device
**object**
Device resolutions given as [x,y,inches diagonal].
#### init()
#### circle(pos, radius, color)
#### poly(points, color, transform)
#### line(points, color = Color.white, thickness = 1, transform)
#### point(pos,size,color = Color.blue)
#### cross(pos, size, color = Color.red)
Draw a cross centered at pos, with arm length size.
#### arrow(start, end, color = Color.red, wingspan = 4, wingangle = 10)
Draw an arrow from start to end, with wings of length wingspan at angle wingangle.
#### coordinate(pos, size, color)
#### boundingbox(bb, color = Color.white)
#### rectangle(lowerleft, upperright, color)
Draw a rectangle, with its corners at lowerleft and upperright.
#### box(pos, wh, color = Color.white)
#### window(pos, wh, color)
#### text(str, pos, size = 1, color = Color.white, wrap = -1, anchor = [0,1], cursor = -1)
#### image(tex, pos, scale = 1, rotation = 0, color = Color.white, dimensions = [tex.width, tex.height])
#### fontcache
**object**
#### set_font(path, size)

1
docs/api/samediff.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:12] warn, script: Cannot print the API of something that isn't an object.

1
docs/api/say.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:10] warn, script: Cannot print the API of something that isn't an object.

24
docs/api/shape.md Normal file
View file

@ -0,0 +1,24 @@
# shape
#### box(w,h)
#### sphere
**object**
#### circle
**object**
#### ngon(radius, n)
#### arc(radius, angle, n, start = 0)

31
docs/api/sim.md Normal file
View file

@ -0,0 +1,31 @@
# sim
#### mode
**string**
#### play()
#### playing()
#### pause()
#### paused()
#### step()
#### stepping()

21
docs/api/steam.md Normal file
View file

@ -0,0 +1,21 @@
# steam
#### init()
#### achievements
**object**
#### app
**object**
#### cloud
**object**

33
docs/api/texture.md Normal file
View file

@ -0,0 +1,33 @@
at <anonymous> (scripts/engine.js:198)
at <eval> (C eval)
at get width (native)
at <anonymous> (scripts/debug.js:185)
at <anonymous> (scripts/debug.js:223)
at <anonymous> (scripts/std.js:385)
at cmd_args (scripts/std.js:458)
at <eval> (C eval)
USE REPORT
scripts/base.js 5.249 ms
scripts/render.js 1.376 ms
scripts/debug.js 583.5 us
scripts/input.js 1.117 ms
scripts/std.js 1.244 ms
scripts/diff.js 212.4 us
scripts/color.js 974.6 us
scripts/gui.js 772.7 us
scripts/tween.js 592.2 us
scripts/ai.js 180.3 us
scripts/physics.js 129.8 us
scripts/geometry.js 244.5 us
scripts/spline.js 308.4 us
scripts/components.js 1.976 ms
scripts/actor.js 224.7 us
scripts/entity.js 2.333 ms
scripts/widget.js 517.9 us
scripts/mum.js 80.06 us
scripts/editor.js 19.23 ms
ENTITY REPORT
scripts/engine.js:501: [2024-07-03 12:13:10] info, script: QUITTING

115
docs/api/time.md Normal file
View file

@ -0,0 +1,115 @@
# time
Functions for manipulating time.
#### now()
Get the time now.
#### computer_dst()
Return true if the computer is in daylight savings.
#### computer_zone()
Get the time zone of the running computer.
#### hour2minute()
#### day2hour()
#### minute2second()
#### week2day()
#### strparse
**object**
#### second
**number**
Earth-seconds in a second.
#### minute
**number**
Seconds in a minute.
#### hour
**number**
Seconds in an hour.
#### day
**number**
Seconds in a day.
#### week
**number**
Seconds in a week.
#### weekdays
**array**
Names of the days of the week.
#### monthstr
**array**
Full names of the months of the year.
#### epoch
**number**
Times are expressed in terms of day 0 at hms 0 of this year.
#### isleap(year)
Return true if the given year is a leapyear.
#### yearsize(y)
Given a year, return the number of days in that year.
#### timecode(t, fps = 24)
#### monthdays
**array**
Number of days in each month.
#### zones
**object**
#### record(num, zone = this.computer_zone()
Given a time, return an object with time fields.
#### number(rec)
Return the number representation of a given time.
#### fmt
**string**
Default format for time.
#### text(num, fmt = this.fmt, zone)
Return a text formatted time.

14
docs/api/timer.md Normal file
View file

@ -0,0 +1,14 @@
# timer
#### update(dt)
#### kill()
#### delay(fn, secs)

15
docs/api/tween.md Normal file
View file

@ -0,0 +1,15 @@
# Tween
#### default
**object**
#### start(obj, target, tvals, options)
#### make(obj, target, tvals, options)

1
docs/api/undefined.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:195: [2024-07-03 12:13:14] warn, script: Cannot print the API of 'undefined', as it was not found.

20
docs/api/ur.md Normal file
View file

@ -0,0 +1,20 @@
# ur
#### _list
**array**
[
"camera2d",
"sprite"
]
#### camera2d
**object**
#### sprite
**object**

1
docs/api/use.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:10] warn, script: Cannot print the API of something that isn't an object.

20
docs/api/window.md Normal file
View file

@ -0,0 +1,20 @@
# window
#### size
**array**
[
500,
500
]
#### mode
**string**
#### editor
**boolean**

1
docs/api/world_start.md Normal file
View file

@ -0,0 +1 @@
scripts/debug.js:205: [2024-07-03 12:13:10] warn, script: Cannot print the API of something that isn't an object.

6
docs/api/yaml.md Normal file
View file

@ -0,0 +1,6 @@
# yaml
#### tojson(yaml)

180
docs/engine_tour/actors.md Normal file
View file

@ -0,0 +1,180 @@
# Actors
The fundamental tool for building in Prosperon is the actor system. Actors run independently from each other. Actors are defined by a combination of code and data. All actors have a *master* which controls certain properties of the actor.
The most masterful actor is the *Empyrean*. The first actor you create will have the Empyrean as its master. Subsequent actors can use any other actor as its master.
| fn | description |
|---------------------|----------------------------------------------------------|
| spawn(text, config) | Creates an actor as the padawan of this one, using text |
| kill() | Kills an actor |
| delay(fn, seconds) | Calls 'fn' after 'seconds' with the context of the actor |
### Actor Lifetime
When an actor dies, all of the actors that have it as their master will die as well.
### Turns
Actors get fragments of time called a *turn*. Actors which belong to different systems can have different lengths of turns.
### Actor files
Actor files end with the extension *.jso*. They list a series of functions to call on a newly formed actor. Actors have a number of useful functions which are called as defined.
| function | call time |
|----------|----------------------------------------------------------|
| start | The first function called when the actor is in the world |
| update | Called once per turn |
| gui | Called on GUI draw |
| stop | Called when the actor is killed |
| gizmo | Called by the editor when the entity is selected |
!!! scholium
Create a new actor, then kill it.
```
var act_die_call = function() {
console.log(`Actor ${this.id} has died.`);
}
var act1 = Empyrean.spawn();
var act2 = actor1.spawn();
act1.stop = act_die_call;
act2.stop = act_die_call;
Empyrean.kill(); /* Error: The Empyrean cannot be killed */
act1.kill();
act2.kill(); /* Error: act2 has been killed because act1 was */
```
!!! scholium
Now simplify by putting the code into a file named *hello.jso*.
```
this.stop = function() {
console.log(`Actor ${this.id} has died.`);
}
```
Now spawn two actors using it.
```
var act1 = Empyrean.spawn("hello.jso");
var act2 = act1.spawn("hello.jso");
```
### Actor configuration
Actors can be created using an optional configuration file. A configuration file is one of any accepted data types. Currently, JSON or [[https://www.crockford.com/nota.html][Nota]]. Configuration files are loaded after an actor's script file, overwriting any defined values on it.
!!! scholium
Add a name for the actor to take on using a configuration file named *hello.json*.
```
{
"name": "Actor 1"
}
```
Now create *hello.jso* to use it.
```
this.start = function() { console.log(`I, ${this.name}, have been created.`); }
```
## Entities
Game worlds are made of entities. Entities are a type of actor with a number of useful properties. Entities can only be created on the actor named *Primum*. The Primum is the outermost actor with a physical space. While Actors are more abstract, Entities exist in a definite space, with a position, rotation, and so on. Entities can respond to physics and play sounds. Anything which can be thought of as having a position in space should be an entitiy.
!!! scholium
The first and most masterful entity is the Primum. The Primum has no components, and its rotation and position are zero. It defines the center of the game.
In editor mode, when an entity moves, all of its *padawans* also move.
When the game is actively simulating, this only holds if there are physical constraints between them.
Prosperon automatically generates physical pin constraints between objects with the appropriate physical properties.
### Adding Components
Entities can have *components*. Components are essentially javascript wrappers over C code into the engine. Scripting is done to set the components up on entities, after which most of the work is done by the C plugin.
!!! scholium
For example, to render an image, set up a *sprite* component on an entity and point its path to an image on your harddrive.
```
var ent = Empyrean.spawn();
var spr = ent.add_component(component.sprite);
spr.path = "image.png";
```
Put that into your config file and run `prosperon`. You should see the contents of "image.png" on the screen.
Try using an animated gif. Prosperon has native support for gif animations!
Components only work in the context of an entity. They have no meaning outside of a physical object in the world. They have no inherent scripting capabilities.
While components can be added via scripting, it is easier to add them via the editor, as we will later see.
### Ur system
When prosperon starts, it searches for urs by name. Any file ending in ".jso" or ".json" will be interpereted as an ur, with same named jso and json being applied as (text, config) for an ur. A jso or json alone also constitute an ur.
An ur can also be defined by a json file. If an ur is found, it takes predecent over auto generated urs. The json of an ur looks like this:
| field | description |
|----|----|
| text | Path to a script file, or array of script files, to apply to the object |
| data | Path to a json file, or array of json files, to apply to the object |
Any ur file with this sort of json creates an ur which can be created in the game. A file named "box.ur" will be ingested and be available as "ur.box". When saving differences, it creates a json file with the same name as an ur (in this case, "box.json").
!!! scholium
Create an ur from the *hello* files above, and then spawn it.
```
ur.create("hello", "hello.jso", "hello.json");
Primum.spawn(ur.hello);
```
When creating an actor from source files, all of its setup must take place. In this example, the setup happens during *ur.create*, and spawning is simply a matter of prototyping it.
This method allows high composability of game objects.
If an entity is created without an ur, is ur is defined as its given text and data. It cannot be saved. It must be given a new ur name.
Objects can be composed on the fly by stringing together urs. For example, a "2x.json" might define scale as 2x. Then, you can create a goblin with `ur.goblin`, or a large goblin with `ur.goblin.2x`. This creates a goblin object, and then applies the 2x scripts and jsons onto the object.
### Urs in game
Each ur has the following fields.
| field | description |
|-----------|-------------------------------------------------------------|
| instances | An array of instances of this ur |
| name | Name of the ur |
| text | Path to the script file |
| data | Object to write to a newly generated actor |
| proto | An object that looks like a freshly made entity from the ur |
An *ur* has a full path given like `ur.goblin.big`. `goblin` and `big` can both possibly have a *.jso* script as well as a *data* file.
When `goblin.big` is created, the new object has the `goblin` script run on it, followed by the `big` script. The `data` fields consist of objects prototyped from each other, so that the `__proto__` of `big.data` is `goblin.data`. All fields of this objects are assigned to the `big goblin`.
The unaltered form of every ur-based-entity is saved in the ur's `proto` field. As you edit objects, the differences between how your object is now, compared to its `ur.proto` is a list of differences. These differences can be rolled into the `ur`, or saved as a subtype.
### Prototyping Entities
Ur types are the prototype of created entities. This makes it trivial to change huge swathes of the game, or make tiny adjustments to single objects, in a natural and intuitive way. When a value is changed on an entity, it is private. When a value is changed on an ur, it propogates to all entities. Values cannot be added or removed in subtypes.
Entities all have the following functions to assist with this:
| function | use |
|---------------|---------------------------------------------|
| clone(parent) | Create an entity prototyped from the parent |
| dup(parent) | Create an exact duplicate of the parent |
| revert() | Removes all local changes on the entity |
Speaking of practical experience, is best for ur prototype chains to be shallow.
### Spawning
Actor data and ur types can remember which entities were contained in it when saving. They are stored in the *objects* field. When an entity with an *objects* field is spawned, it spawns all of the objects listed in turn.
When an entity is spawned, it is addressable directly through its master entity. Its name is generated from its file or ur type name.
!!! scholium
Let's take a simple RPG game.
```
Primum
level1
orc
goblin
human
sword
ui
```
The orc, for example, is addressable by `Primum.level1.orc`. The `human` has a `sword` spawned underneath it. When he is killed, his sword also disappears.

View file

@ -0,0 +1,57 @@
# Editor
Prosperon's visual editor is an assistant for the creation and editing of your game entities and actors. In the editor, all ur types are loaded, and assets are constantly monitored for changes for hot reloading.
To initiate it, execute `prosperon`.
## Editing entities
The desktop is the topmost entity that exists in the editor. Instead of editing specific files, you simply load them into your desktop, and go from there. This makes it easier to see two different entities simultaneously so you can ensure changes to one are congruous with the vision for the others.
The main editor view is made up of entities. Each entity can have a number of components attached to it. When an entity is selected, its name, position, and list of components are listed.
Basic use of the editor involves spawning new entities, or ones from already made ur types, editing them, and then saving them as new ur types or overwriting the ones they spawned from. Specific tools have been written to make editing components and levels easier than with a text editor, and the editor is easily extendable for your own purposes.
Assign the entity's *gizmo* property to a function to have that function called each gui rendering frame.
## The REPL
The REPL lets you poke around in the game. It makes iteration and experimentation fast, fun, and easy.
The symbol `$` references the current REPL entity. If no entity is selected, the REPL entity is the currently edited one. Otherwise, it is the selected entity, or group of entities, as an array.
!!! scholium
Easily run commands on multiple entities using Javascript functions like for each.
```
$.forEach(e => console.log(e.pos));
```
The REPL is a powerful tool for editing your game. Arbitrary code can be ran in it, meaning any esoteric activity you need done for your game can be done easily. Commonly used functions should be copied into your /editorconfig.js/ to be called and used at will.
## Playing the game
Playing the game involves running the game from a special /debug.js/ file, or from the beginning, as if the game were packaged and shipped.
| key | action |
|-------|-----------------------------------------------------|
| f5 | Play the game, starting with entry point /debug.js/ |
| f6 | Play the game from the beginning |
While playing the game, a limited editor is available that allows for simple debugging tasks.
| key | action |
|-----|-----------------------------|
| C-p | Pause |
| M-p | One time step |
| C-q | Quit play, return to editor |
## Script Editor
Prosperon comes with an in-engine script editor. It implements a subset of emacs, and adds a few engine specific features.
### Syntax coloring? ... nope!
The editor that ships with Prosperon has *context coloring*, which is a good deal more useful than syntax coloring.
## Debugging
Debugging functions are mapped to the F buttons, and are available in any debug build of the game. Pressing the specified key toggles the feature; pressing it with /alt/ shows a legend for that feature.
| key | description |
|-----|----------------------------|
| F1 | Draw physics info |
| F3 | Draw bounding boxes |
| F12 | Draw gui info |

View file

@ -0,0 +1,52 @@
# Exporting your game
Prosperon is a multiplatform engine. Bundling your game for these platforms essentially involves three steps:
- Baking static content
- Conversion of assets
- Packing into a CDB
To distribute your game for a given platform, run `prosperon build {platform}`.
| platform |
|----------|
| Linux |
| MacOS |
| Windows |
You will find your game ready to go. Rename the executable to the name of your game and run it to play. Congratulations!
## Building static content
Static content creation involves any number of optimizations.
- Bitmap font creation
- Texture map creation
Creation of these assets is invisible. Prosperon updates its understanding of how to pull assets based on the existance of these packed ones.
## Converting assets
Images, videos, and sounds, are converted to assets most suitable for the target platform. This may be for speed or simple compatability. *You do not need to do anything*. Use your preferred asset types during production.
## Packing into a CDB
A *cdb* is known as a "constant database". It is a write once type of database, with extremely fast retrieval times. Packing your game into a cdb means to create a database with key:value pairs of the filenames of your game. The Prosperon executable is already packed with a core cdb. Your game assets are packed alongside it as the game cdb.
You can create your game's cdb by running `prosperon -b`. You will find a *game.cdb* in the root directory.
* Modding & Patching
When an asset is requested in Prosperon, it is searched for in the following manner.
1. The cwd
2. The game cdb (not necessarily present)
3. The core cdb
Game modification is trivial using this described system. By putting an asset in the same path as the asset's location in the game cdb, when that asset is requested it will be pulled from the file system instead of the game cdb.
Given a Prosperon-built game, you can unpack its content into a directory by running `prosperon unpack {game}`.
## Shipping
Once a game's assets are modified, it may be desirable to ship them. Run `prosperon patch create {game}` to create a /patch.cdb/ filled only with the files that are different compared to those found in the /game.cdb/ in the /game/.
To update /game/ to use the new patch, run `prosperon patch apply {patch}`, replacing /patch/ with the name of the cdb file generated above.
Many patches can be bundled by running `prosperon patch bundle {list of patches}`. This creates a patch that will update the game as if the user had updated each patch in order.
Mods can be distributed with the same idea.

9
docs/engine_tour/gui.md Normal file
View file

@ -0,0 +1,9 @@
# GUI
Game GUIs are written by registering an entity's `gui` property to a function, or its `hud` property.
`gui` draws in window space, where the bottom left corner is `[0,0]`. `hud` draws in screen space. In either of these, you can call "render" functions directly.
`draw` draws in world space, and mum functions can equally be used there.
## MUM
The GUI system which ships with Prosperon is called *MUM*. MUM is a declarative, immediate mode HUD system. While Imgui is designed to make it easy to make editor-like controls, mum is designed to be easy to make video game huds.

View file

@ -0,0 +1,2 @@
# Engine Tour

52
docs/engine_tour/input.md Normal file
View file

@ -0,0 +1,52 @@
# Input
Input is done in a highly generic and customizable manner. *players* can take control of any object (actor or otherwise) in Prosperon, after which it is referred to as a *pawn* of a player. If the object has a defined *input* object, it is a valid pawn. One player can have many pawns, but each pawn may have only one player.
Pawns are added as a stack, with the newest ones getting priority, and handled first. It is possible for pawns to block input to lower pawns on the stack.
```
*newest*
car <== When a key is pressed, this is the first pawn to handle input
player
ui <== /block/ is set to true here, so editor recieves no input!
editor
*oldest*
```
The default player can be obtained with `Player.players[0]`. Players are all local, and the highest number is determined by platform.
The **input** object defines a number of keys or actions, with their values being functions.
## Editor input
The editor input style defines keystrokes. It is good for custom editors, or any sort of game that requires many hotkeys. Keystrokes are case sensitive and can be augmented with auxiliary keys.
| symbol | key |
|--------|-------|
| C | ctrl |
| M | alt |
| S | super |
```
var orc = Primum.spawn(ur.orc);
orc.inputs = {};
orc.inputs.a = function() { ... };
orc.inputs.A = function() { ... }; /* This is only called with a capital A! */
orc.inputs['C-a'] = function() { ... }; /* Control-a */
Player.players[0].control(orc); /* player 0 is now in control of the orc */
```
The input object can be modified to customize how it handles input.
| property | type | effect |
|----------------|----------|--------------------------------------|
| post | function | called after any input is processed |
| =release_post= | function | called after any input is released |
| fallthru | bool | false if input should stop with this |
| block | bool | true if input should stop with this |
The input can be modified by setting properties on the associated function.
| property | type | effect |
|----------|----------|--------------------------------------------------------|
| released | function | Called when the input is released |
| rep | bool | true if holding the input should repeatedly trigger it |
| down | function | called while the input is down |

View file

@ -0,0 +1,2 @@
# Physics
Prospeorn comes with the [[https://chipmunk-physics.net][Chipmunk]] physics engine built in. It is a fast, stable physics solution. All entities are assumed to be physics based objects, and components can be added to them to enable more physics features.

View file

@ -0,0 +1,9 @@
# Profiling
There are a handful of profiling methods available to you.
## Frame by frame profile
## Cpu instrumentation
## Game stats

View file

@ -0,0 +1,57 @@
# Resources
Assets can generally be used simply with their filename. Assets can be modified with a sidecar file named *filename.asset*, so, a file `ball.png` can have additional parameters through its `ball.png.asset` file.
| sigil | meaning |
|--------|------------------------|
| \slash | root of project |
| @ | root of save directory |
| # | root of link |
Resources can be referenced in a relative manner by actor scripts. When it comes to actors using assets, relative filepaths are useful and encouraged.
```
/
score.wav
/bumper
hit.wav
bumper.jso
/ball
hit.wav
ball.jso
```
Path resolution occurs during actor creation. In effect, a reference to *hit.wav* in *bumper.jso* will resolve to the absolute path */bumper/hit.wav*.
If the asset is not found, it is searched for until the project root is reached. The bumper can reference *score.wav* and have the path resolution take place. Later, if the it is decided for the bumper to have a unique score sound, a new /score.wav/ can be placed in its folder and it will work without changing any code.
!!! caution
Because the path is resolved during object load, you will need to fresh the bumper's ur or spawn a new bumper for it to use the newly placed /score.wav/.
#### Links
Links can be specified using the "#" sign. These are shortcuts you can specify for large projects. Specify them in the array `Resources.links`.
An example is of the form `trees:/world/assets/nature/trees`. Links are called with `#`, so you can now make a "fern" with `Primum.spawn("#trees/fern.jso")`.
### Ur auto creation
Instead of coding all the ur type creation by hand, Prosperon can automatically search your project's folder and create the ur types for you. Any /[name].jso/ file is converted into an ur with the name. Any /[name].json/ file is then applied over it, should it exist. If there is a /.json/ file without a corresponding /.jso/, it can still be turned into an ur, if it is a valid ur format.
Folders and files beginning with a '.' (hidden) or a '_' will be ignored for ur creation.
The folder hierarchy of your file system determines the ur prototype chain. /.jso/ files inside of a folder will be subtyped off the folder ur name.
Only one ur of any name can be created.
```
@/
flipper.js
flipper/
left.js
@/
flipper/
flipper.js
left/
left.js
```
`prototypes.generate_ur(path)` will generate all ur-types for a given path. You can preload specific levels this way, or the entire game using `prototypes.generate_ur('.')`. If your game is small enough, this can have a massive runtime improvement.

View file

@ -0,0 +1,61 @@
# Scripting
The scripting language used in Prosperon is Javascript, with QuickJS. It is ES2023 compliant. It is fast.
!!! scholium
Javascript is used here mostly to set up objects and tear them down. Although computationally expensive tasks can be done using QuickJS, Prosperon makes it easy to extend with raw C.
### How Prosperon games are structured
Prosperon schews the CommonJS and ES module systems for a custom one suitable for a computer game actor model. It is more restricted than either system, while retaining their full power.
Prosperon games are structured into two types of source files:
- scripts
- actors
Scripts end with a return statement. A script can return a function, an object of functions, or any other sort of value.
!!! scholium
It is a common requirement to add some amount of functionality to an object. It can be easily done with a script file.
```
*script.js*
function hello() { say("hello"); };
return hello;
```
```
var o = {};
o.use("hello.js");
o.hello();
```
The `use` function on any object loads a module, and `assign`s its return to the object.
Scripts are loaded into memory only once. Further `use` statements only generate references to the statements. Because *scripts* are executed in a lambda environment, any `var` declared inside the script files are effectively private variables, persistent variables.
In a *script*, `this` refers to `undefined`. It is nothng.
In an *actor* source file, `this` refers to the actor. Actors do not end in a `return` statement. *actor* source is intended to set up a new agent in your game. Set up the new entity by loading modules and assigning functions to `this`.
### Script entry points
The first way you can customize Prosperon is by adding scripts to the folder you're running it from. Any file ending with *.js* is a *script* which can be ran by Prosperon.
| script | When called |
|-----------------|---------------------------------------------|
| config.js | First script on Prosperon load |
| game.js | Entry point for running the game |
| editorconfig.js | Entry point for running the editor |
| predbg.js | Called before running debug |
| debug.js | Debug set up |
| dbgret.js | After stopping debug mode, used for cleanup |
!!! scholium
Try it out. Add a script called `config.js` to your folder, with this.
```
console.log("Hello world!");
Game.quit();
```
Run `prosperon`. You will see "Hello world!" in the console, and it shuts down.
Using `config.js` and `game.js`, you can write an entire game, without reaching any further. When you want to populate a world with independent actors, entities are what you will reach for.

View file

@ -0,0 +1,16 @@
# Getting Started
## Installation
### Linux & MacOS
Install the most [[https://prosperon.dev/download][recent binaries]] into your `$PATH`.
### Windows
Copy the executable into any folder and run it. If no game is deteced, it scaffolds for you.
### Building
You will need `sokol-shdc` in the top of your directory. Then, `make shaders` and `make`. The command `make install` copies it to your home's `.bin` path.
## Playing your first game
Download any of the completed example projects. Run `prosperon play` in the folder.
Poke around the example projects. You will find it refreshingly straight forward.

1
docs/guides/index.md Normal file
View file

@ -0,0 +1 @@
A collection of examples for doing common things with Prosperon.

1
docs/index.md Normal file
View file

@ -0,0 +1 @@
Prosperon is built in a code-first fashion.

View file

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

View file

Before

Width:  |  Height:  |  Size: 76 KiB

After

Width:  |  Height:  |  Size: 76 KiB

Some files were not shown because too many files have changed in this diff Show more