General Guidelines

A Didactic Editor for Games

While FUDGE may additionally become an editor for "didactic games" at a later stage in its development, it is foremost and for now solely a "didactic editor" for games. That means, the main goal is to make the structures and processes of games and their development cleary visible and understandable and the use of FUDGE as easy as possible, while maintaining the flexibilty and generic application. All design decisions must obey to this, other issues such as performance or visual effects have lower priority.

Runtime and Compiletime Performance

A FUDGE project runs directly in the browser without further compilation, except of the compilations that happen on the fly during design time such as TypeScript compilation. For other platforms such as native desktop or native mobile, packaging and further compilation may be required and is acceptable. It's also acceptable to offer special tools to process or compile data for optimization in order to gain performance or reduce loading sizes at runtime.

Design

The development of FUDGE strictly follows the best practices of software-design and -engineering. The team designs the development using UML and Scribbles prior to coding and other activities. The resulting design documentation is available to the team at all times, discussed and improved as applicable before implementation of any code.

Version Control and Collaboration

FUDGE is hosted on Github. All documents must be shared through this platform, other platforms or email must not be used. The team, if not present in the same room, communicates mainly via Github-issues. At all meetings, the team writes protocols and uploads them to the repository. The filenames of those protocols must start with the date in the form yymmdd and must be reflected and made available through links in the readme-file of the folder.
When coding, each team member creates a branch for new implementations to develop and test separately without interfering with other team members. Once the code is in a desirable and stable state, it may be merged to the master branch during a team meeting. Thus, each team member can help to merge and immediately test the integration, especially with parts of FUDGE they consider to be affected or are specialized in.

Code Documentation

Code must be documented using the JSDoc format for comments. Export the API-Documentation with TypeDoc. Make use of links to this wiki and other resources to further explain concepts and details of FUDGE.

Tests

Create tests for major aspects of the engine that make it easy to test it at all times, even for untrained staff. Many tests can not be evaluated automatically and require a human observer. Therefore, tests stick to a common format which is about to be introduced to all tests. A splash screen appears at the start of the test to tell the user how to interact and what to look out for. If a test is completely or partially evaluated by itself, output in the console should be used to inform the tester. As of April 2020, the format is implemented e.g. in the audio tests.

Structure

The directory- and file-structure is set up to enforce clearity and ease of use. Each class lives in a separate file, except only for collections of extremely small classes each consisting of only a few lines of code. Files are grouped by focus/task/heritance in subdirectories. The FUDGE-Core, which is the minimal required to run a game, sits in a separate directory and has its individual namespace. So does the editor. An application using FUDGE is again separated. The reference-directive in tsconfig.json (TS Version > 3) makes it easy to adjust links.

Integrated Help System (to be implemented)

• Hover, F1+Hover, F1+Click
• Interactive Tutorials! -> System may later be used for educational software/games
• Screencasts

User Interface (design notes)

• variable screen layout
• dockable windows
• pure HTML/CSS/TS + Angular or similar etc.
• UI-creation from and for sripts (see Unity-Inspector)
• support Help System
• only standard elements like text-fields, steppers, checkboxes, sliders etc.
• support skins and a well design system for storing and exchanging them
• components
  • bring their individual interfaces for the editor
  • script-interfaces can be designed by the script developer
  • may invoke an extra editor window for complex manipulation e.g. animation, drawing
• text
  • may not be literaly defined in code but referenced (except console.logging)
  • must be defined in external files, preferrably in JSON-Format
• gizmos, icons, 3d-icons in the 3d-sceneview
• renders
  • as overlay
  • or within the scene, supporting full interactivity

Time

In order to control time, all timing is based on a special time class. So animations, timed events and timebased behaviour can be slowed down or sped up at will.
Animation may be time or frame based. Framebased animation is important when prerendering 2D-spritesheets from vectoranimations. Framebased animation also allows for the synchronisation of animations in a parent-child-relationship. Users can choose between the animation types and enforce prerendering for optimization.
With this time class it is also possible to do postsimulations of presaved game sequences and watch them at different speeds or even stop them for further investigation and debugging.

Handling errors and exceptions

Don't make the system too smart trying to help the user. Don't implement magic that takes care of things when the user apparently uses the system wrongly. Instead, make use of exceptions, use try/catch/finally and throw exceptions. Use the standard Javascript error objects as listed here https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#Error_types