Code and data of Castle Game Engine website

Editing

We use a few ways to edit the content:

AsciiDoctor for static pages

Example of page written this way: https://castle-engine.io/gltf , content in htdocs/doc/gltf.adoc .

To edit: Fork this repository (cge-www) and edit the *.adoc pages in htdocs/doc/ subdirectory. Then create a pull request.

See https://asciidoctor.org/ for an overview of the AsciiDoctor language. To preview your edits:

• look at GitHub preview of your file
• or run asciidoctor xxx.adoc
• or (more complicated but presents complete preview) follow the "Testing Locally" instructions below to set up your own local copy of CGE website.

We support additional macros within AsciiDoctor:

• cgeref: Place link to API reference of some Pascal identifier, with optional customized title. The Pascal identifier is automatically found in global identifiers in latest CGE API docs (using https://pasdoc.github.io/PhpOutput underneath). Use like this:

  cgeref:TCastleScene[]
  cgeref:TCastleScene[link text for TCastleScene]
  

  If you want to write [ or ] inside the link title, write {{{ or }}} instead. They will be replaced with [ or ] . Like

  cgeref:TMessaging.Send[Messaging.Send({{{'message-1','some-parameter'}}})]
  

• cgeimg: Place images, using CGE style. Images can be floating (on the right) or be a block within page content flow.

  cgeimg::block[aaa.png|Description of AAA,bbb.png|Description of BBB]
  cgeimg::float[aaa.png|Description of AAA,bbb.png|Description of BBB]
  
  // This example has image filenames that actually exist, so go ahead and try pasting it some .adoc
  cgeimg::block[dragon_0_wire.png|Dragon,gamma_nogamma_helmet.png|Gamma Correction]
  cgeimg::float[dragon_0_wire.png|Dragon,gamma_nogamma_helmet.png|Gamma Correction]
  
  // Additional whitespace and newlines are allowed for cgeimg, so you can write it like this too
  cgeimg::block[
    dragon_0_wire.png|Dragon,
    gamma_nogamma_helmet.png|Gamma Correction
  ]
  

  Note: you can use backslash to write an ordinary comma within the image description.

  cgeimg::block[aaa.png|A very\, very\, very long description]
  
  cgeimg::block[aaa.png|Can be used to escape bar too\| <- like this]
  
  cgeimg::block[aaa.png|Double your backslashes to be safe, \\ <- this outputs a backslash]
  

  We expect to find referenced images (aaa.png,bbb.png in examples below) in htdocs/images/original_size/. You can regenerate all thumbnails using cd htdocs/images/ && make, though at development they will also be regenerated as-needed by PHP. To allow the PHP to do this,

  • install ImageMagick (convert must be on $PATH),

  • install Ffmpeg (ffmpeg must be on $PATH) to process some GIFs,

  • GNU make,

  • and make sure PHP has permissions to write within proper images/ subdirectories: chmod -R a+rwX htdocs/images/*_size/.

  • Once, right after cloning this repo from GIT, it is useful to execute make do-not-regenerate-existing-images to avoid regenerating all thumbnails because their timestamps are older than the source images.

  The idea is that (at development) you

  • Just drop new images to htdocs/images/original_size/ (hint: make it a bookmark in your file manager)

  • Add cgeimg to .adoc source code to view them

  • Refresh the local page like http://localhost:8777/curves_tool , which will (in development) automatically regenerate AsciiDoctor -> HTML, and will generate thumbnails if missing. (hint: set up a key shortcut in your text editor to refresh the www browser view of this page)

• Note: AsciiDoctor macros above are not really implemented as AsciiDoctor macros in Ruby, following

  • https://docs.asciidoctor.org/asciidoctor/latest/extensions/inline-macro-processor/
  • https://docs.asciidoctor.org/asciidoctorj/latest/extensions/block-macro-processor/
  • https://docs.asciidoctor.org/asciidoctor/latest/extensions/block-macro-processor/

  Instead they are implemented using PHP, as replacements on top of the AsciiDoctor processing. Why? Because we needed to implement them in PHP too, as our pages need these functions in PHP too, and for Wordpress shortcodes too.

PHP for static pages

Example of page written this way: https://castle-engine.io/compiling_from_source.php , content in htdocs/compiling_from_source.php .

To edit: Fork this repository, edit php file in htdocs/, and create a pull request.

To test your modifications, you can follow the "Testing Locally" instructions below. If these instructions look too complicated, just ignore them for simple modifications --- the PHP files are mostly using trivial HTML with small PHP additions (like PHP castle_header, cgeRef functions) so if you understand basic HTML, you can probably figure out what is going on.

Most important PHP functions are:

• castle_header, castle_footer to start every CGE webpage

• cgeRef, cgeImg -- consistent with above-described AsciiDoctor macros. Example usage:

  <?php
  echo cgeImg('float', array(
    array('filename' => 'view_events_screen.png', 'titlealt' => 'Plane flying on the mountain background - game'),
    array('filename' => 'view_events_biplane_4_resized.png', 'titlealt' => 'Plane flying on the mountain background - design'),
  ));
  ?>
  
  Something descends from <?php echo cgeRef('TCastleView'); ?> and manages something.
  

Wordpress for news

Example page: https://castle-engine.io/wp/ .

To edit: contact Michalis Kamburelis ([email protected]) to get a Wordpress account. Page contents are in Wordpress database.

Most important Wordpress shortcodes are:

• [gallery...] - modified Wordpress gallery to use castle_thumbs (quite like cgeImg) to display Wordpress images

• [cgeref...], [cgeimg....] -- consistent with above-described AsciiDoctor macros. Example usage:

  [cgeimg block images="dragon_0_wire.png|Dragon,gamma_nogamma_helmet.png|Gamma Correction"]
  
  [cgeref id=TCastleScene]
  [cgeref id=TCastleScene title="link text for TCastleScene"]
  

• We write most Wordpress posts using Markdown (easier than writing HTML, and good enough for our purposes), processed by Jetpack, see Markdown in Jetpack classic editor and Quick Reference.

• We use Urvanov Syntax Highlighter to highlight code blocks in the posts. Mark the Pascal code blocks in Markdown using 3 backticks with language pascal (TODO: though the language selection is lost during Jetpack processing now, but still write it for the future; for now, we just configured the plugin to use Pascal by default).

Layout of files

• htdocs/ is exactly what goes into https://castle-engine.io/

  • htdocs/doc/ are documents in AsciiDoctor. Subset of https://castle-engine.io/ is generated from AsciiDoctor.

  • htdocs/wp/ is our Wordpress installation, used right now to manage news.

• screenshots/ are only a copy (sometimes with better resolution) of the same screenshots that are available on SF screenshot page of our project.

• scripts/ are various scripts, usually in bash, helpful to manage the website.

  • scripts/remote/ are meant to be run when logged on castle-engine.io through ssh.

  • Rest of scripts/ can be run on a local version, cloned somewhere on your local computer.

Testing Locally

• Install Apache (or any other web server that can handle PHP)

  • Enable mod_rewrite. On Debian-based systems, do sudo a2enmod rewrite && sudo service apache2 restart.

• Install PHP

• Make htdocs/ referenced from Apache. There are may ways to do this. I advise to do this on Linux and make the website root accessible under URL like http://localhost:8777/ (which would open htdocs/index.php file in this repo).

  • Listen on port 8777. Edit /etc/apache2/ports.conf and add Listen 127.0.0.1:8777.

    Note: There's nothing special about the 8777 port. It just seems unused by most other software (looking at https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers ), so it is likely non-conflicting with anything else on your system.

  • Create new site, following apache-sample.conf example from this repo. You can copy and adjust it to /etc/apache2/sites-available/cge-www.conf . Or even symlink it, if you use the same path as me: cd /etc/apache2/sites-available && sudo ln -s ~/sources/castle-engine/cge-www/apache-sample.conf cge-www.conf.

  • Enable it:

    • On Debian-based systems, do sudo a2ensite cge-www && sudo service apache2 restart.

    • On Arch Linux, follow https://wiki.archlinux.org/title/Apache_HTTP_Server .

  • Make sure the Apache web user has access to at least read the files in htdocs/ and subdirectories.

    • You can make them owned by www-data user, like sudo chown -R www-data:www-data ~/sources/castle-engine/cge-www/htdocs/.
    • Make sure the parent directories are also accessible to www-data, e.g. chmod a+rX ~.
    • Check it all works by sudo -u www-data ls ~/sources/castle-engine/cge-www/htdocs/.
    • To enable comfortable editing with above setup, your own user should be in www-data group as well. sudo adduser $USER www-data (followed by logout + login to refresh group membership) on Debian-based systems will do the trick. And make them group-writeable, like sudo chmod -R g+w htdocs/.

  Now pages that use only our PHP framework, like http://localhost:8777/index.php should work.

  Note that the main page, http://localhost:8777/ , depends on a working Wordpress installation (including the database) -- see below, it will require additional work to see it.

  Note: It is also possible to set this up in non-root, you could even use Apache mod_userdir to place it e.g in http://localhost/~michalis/castle-engine/ . We used to even advise this here, but we don't advise it anymore, as it's a bit more work (need to make sure PHP works in user directories too) and needs adjusting .htaccess to make rewrites/redirects work and / to link to main page (which we use now from both PHP and AsciiDoctor) work OK.

• To enable testing of AsciiDoctor pages, like http://localhost:8777/build_tool :

  • Install AsciiDoctor, CodeRay and Rouge.

    On Debian-like systems, just do apt install asciidoctor coderay ruby-rouge.

    Note: We are in the middle of experimenting with 2 syntax highlighters. On one hard, CodeRay syntax highlighting for Pascal looks better, as it can differentiate between keywords and compiler directives. On the other hand, Rouge supports shell language which is also useful for us. For now, both are installed and doc/common.adoc selects CodeRay, while some pages with many shell blocks (like doc/build_tool.adoc) choose Rouge.

• To enable viewing the main page and other pages depending on Wordpress (http://localhost:8777/, http://localhost:8777/wp/):

  • Install MySQL (on Debian/Ubuntu and derivatives: sudo apt install default-mysql-server).

  • Create empty Wordpress database

    CREATE DATABASE cgewp;
    CREATE USER 'cgewp'@'localhost' IDENTIFIED BY 'devpassword';
    GRANT ALL PRIVILEGES ON cgewp.* TO 'cgewp'@'localhost';
    

  • Install PHP mysql extension (on Debian/Ubuntu and derivatives: sudo apt install php-mysql).

  • When the main page is first opened, configure Wordpress. Just provide any information (username, email, password), it's a local installation, it doesn't really matter.

  • Visit http://localhost:8777/wp/wp-admin/themes.php and change theme to "Castle Game Engine Theme".

  • If you need to import the real content of our Wordpress, contact Michalis.