Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kaveh808/kons-9

Common Lisp 3D Graphics Project
https://github.com/kaveh808/kons-9

3d-animation 3d-graphics common-lisp graphics lisp

Last synced: about 1 month ago
JSON representation

Common Lisp 3D Graphics Project

Lists

README

        

# kons-9

## An IDE For 3D Production

Teaser trailer for the project:

https://www.youtube.com/watch?v=THMzaVDaZP8

**kons-9** is a new 3D computer graphics and animation software system being developed as an **open source project** under the MIT license. It broadly falls under the category of a **3D digital content creation tool**, while providing interesting and unique features not found in other systems. The intention is to develop a **flexible and extensible system** in which can be built a wide variety of application and domain specific tools and packages.

The unique differentiating aspect of **kons-9** is that it combines the power of a **software development IDE** with the visual tools of **3D graphics authoring system**. It does this by being implemented in **Common Lisp**, an **object-oriented dynamic language** which provides powerful facilities for **exploratory development and rapid prototyping** within a live interactive software environment.

This allows for **unlimited extensibility** of the system by both developers and users. In fact, this unique aspect of **kons-9** erases the distinction between developers and end users. Code developed within the kons-9 framework is always first class, not limited to some arbitrary API or scripting language. The source code for the system is available for extension, customization and exploration, and development in new directions, all within a **REPL-based** integrated development environment operating on a **live image of a 3D scene**.

Every user of **kons-9** has at their disposal the same full range of facilities and tools as the original developers of the system. Therefore code developed by them is first class in the sense that it has all the capabilities of code written by the developers of the system. There is no concept of a limited scripting language separate from the source code of the software.

Users of **kons-9** are able to modify 3D classes, subclass and extend them, and add new behaviors as desired. The system is **highly extensible and customizable** to suit different application domains and workflow needs.

**kons-9** can be used as a traditional **user interface driven 3D application** by general artists, or as a **REPL-based development environment** by technical artists and software developers. These two approaches can be seamlessly combined into a flexible and powerful workflow, where non-technical users can immediately benefit from software tools and extensions developed by technical users.

Developers work in a live image of their 3D scene, able to immediately see the results of their code in action. There is no need for a separate compile, link, and load process. Nor does the system have to be restarted to be updated. The REPL-based development experience is **highly interactive** with a **continuous and tight feedback loop**. Class and function definitions can be **modified on the fly** and the **results seen immediately** in the 3D scene. Incremental and exploratory development is facilitated and encouraged by the nature of the system.

Demo of an early version of the software:

https://youtu.be/NJe4isZ7NHI

## How To Join The kons-9 Team

**kons-9** is an open source project under the MIT license. We welcome those wishing to contribute their time and skills.

If you wish to do so, please:

- Watch the project.
- Turn on Notifications so you are aware of the Discussions postings.
- Read the Introductions thread in [Discussions](https://github.com/kaveh808/kons-9/discussions).
- Post your own introduction on the thread.
- Join the Discussions and look at the open Issues.

## How To Run kons-9

This code currently runs in SBCL on MacOS, Linux, and Windows. The system currently uses OpenGL as a graphics engine, though we are working on moving to Vulkan/Metal.

Download the code and load the local directory:

(push (uiop:getcwd) ql:*local-project-directories*)

Load the system:

(ql:quickload "kons-9")

Run the following code to open a 3D view window:

(in-package :kons-9)
(run)

Open `test/demo-kernel.lisp` and start evaluating the blocks of code for the demos. Things should appear in the graphics window. Try the other demo files as well.

Have fun.

## Run the Testsuite as a Batch Job

Use development script `development/testsuite` to run the testsuite as
a batch job. Specific tests can be requested by adding one argument to
the command line, such as

development/testsuite exercise-clamp
development/testsuite testsuite-utils

The following command lists all available tests

development/testsuite list-all-available-tests

## Run the Testsuite from the REPL

Load the system:

(ql:quickload "kons-9/testsuite")

List all available tests with

(kons-9/testsuite:list-available-tests)

Tests are implemented as regular functions and can be run with
statements similar to

(kons-9/testsuite:run-all-tests)

or

(kons-9/testsuite:exercise-clamp)
(kons-9/testsuite:testsuite-utils)

Users not familiar with [Confidence][confidence-home] may want to
review the [quick introduction to Confidence][confidence-intro].

[confidence-home]: https://github.com/melusina-org/cl-confidence
[confidence-intro]: https://github.com/melusina-org/cl-confidence/blob/main/example/example.lisp

## API reference

The [Kons-9 API reference manual](https://kaveh808.github.io/kons-9) is a work-in-progress.

This manual is generated using the [PAX](https://melisgl.github.io/mgl-pax-world/mgl-pax-manual.html) framework and the directives in [`src/api/api.lisp`](src/api/api.lisp).

Updates are automatically published from the `main` branch using Github Actions.

Please contribute to the documentation as you study the Kons-9 source code!

### Building the documentation

Build the documentation in HTML format from a Kons-9 Lisp image:

```
(require :kons-9/api-docs)
(pax:update-asdf-system-html-docs kons-9::@api :kons-9)
```

See [PAX: Utilities for Generating Documentation](https://melisgl.github.io/mgl-pax-world/mgl-pax-manual.html#toc-8-9-utilities-for-generating-documentation). See also [PAX: Documenting in Emacs](https://melisgl.github.io/mgl-pax-world/mgl-pax-manual.html#toc-8-2-documenting-in-emacs) for live Emacs-based documentation browsing.

### Updating API example transcripts

PAX automatically verifies that all examples produce their expected results (see [PAX: Transcripts](https://melisgl.github.io/mgl-pax-world/mgl-pax-manual.html#toc-9-transcripts)). If the consistency checks fail then so will the documentation build and its associated Github Action.

To update a transcript, or create a new one, place the point immediately after the example code inside a docstring and run the Emacs command `mgl-pax-transcribe-last-expression` (see [PAX: Transcribing with Emacs](https://melisgl.github.io/mgl-pax-world/mgl-pax-manual.html#toc-9-2-transcribing-with-emacs)). See the examples in [`api.lisp`](src/api/api.lisp) for reference.

PAX transcripts should be formatted using this markdown syntax:

```cl-transcript (:dynenv pax-dynenv)
...lisp code...
```

The `cl-transcript` directive tells PAX to make consistency checks.

The `:dynenv` directive ensures that the checks are made in a suitable environment e.g. with a fixed random seed.

#### Pitfalls

1. PAX transcript consistency-checks are sensitive to whitespace. Be careful not to edit the whitespace in the generated example output or else the consistency checks will fail. (Be careful of Emacs modes like `ws-butler` potentially causing problems by overzealously stripping trailing whitespace from inside string literals.)

2. PAX emacs commands only started respecting the `:dynenv` directive in version 0.2.1 which at this time of writing has not yet landed in Quicklisp. If you update transcripts using an older version of the PAX Emacs Lisp code the environment (random seed) won't be locked down and the consistency checks might fail.