How to use GitHub Actions with your CGE project to get automatic builds

Posted on

GitHub Actions artifacts

This is now documented in CGE manual about GitHub Actions.

We’ve made it so easy to use GitHub Actions to get automatic builds for your projects, done by GitHub, after every commit. You have to try this 🙂

  1. Download this file: build.yml and place it at .github/workflows/build.yml path in your project. That is, create a subdirectory .github, then subdirectory workflows, then put the build.yml file inside.

    See the sample project castle-game using it.

  2. Then commit, push and just watch the GitHub “Actions” tab as it picks up the commit and automatically rebuilds the project for:

    • Windows (x86_64)
    • Linux (x86_64)
    • Android (APK contains both 32-bit and 64-bit ARM code)
    • macOS (x86_64)

    Ready files are available in the “Artifacts” section. Download them, unpack — ready binary release of your game, for 4 systems above. You don’t need to do builds.

    Note that they will disappear after some time (90 days by default). If you want to preserve them you can e.g. make a GitHub release with them (and maybe even we will automate this too in the future, to make auto-updated “snapshot” release).

The actions execute on GitHub-hosted servers, completely free for open-source projects. They rely on Castle Game Engine Docker image and use the latest CGE “snapshot” revision and latest stable FPC (3.2.2) now. The build is done by executing CGE build tool with proper options. You don’t really need to understand it all — our build.yml just does it for you.

This is my first shot at implementing a new feature in CGE: “Automatic Cloud Builds” that you can quickly turn on when creating new CGE project, and will place a suitable file to integrate your project with

  • Jenkins (your own Jenkins instance, that has to support declarative pipeline and Docker, similar to CGE Jenkins). This implies using a Jenkinsfile like this.

  • GitHub Actions – based on above, this implies using .github/workflows/build.yml.

  • GitLab CI. This means creating a file like .gitlab-ci.yml (example in FPC repo).

Comments on the forum ➤

view3dscene now available also for macOS and Raspberry Pi

Posted on

view3dscene on macOS

You can now download view3dscene builds for macOS (Intel-based macs) and Raspberry Pi. These new platforms are an addition to the existing Linux and Windows builds, that of course remain available too.

view3dscene is a viewer for all 3D and 2D model formats supported by Castle Game Engine, in particular glTF, X3D, VRML, Spine JSON, sprite sheets. It is a useful tool for Castle Game Engine developers (when you double-click on a model in CGE editor we actually open view3dscene), and for anyone else who just wants to view pretty 3D models downloaded from the Internet (test e.g. on glTF files from Sketchfab).

view3dscene snapshots for macOS and Raspberry Pi are automatically rebuild by Jenkins after every commit to view3dscene and Castle Game Engine (that passes a number of automated tests) so they will continue to reflect the very latest features.

macOS notes:

  1. macOS app bundle is not signed (for now). For the first time, you have to run it by clicking with right mouse button, choosing “Open” from the context menu, and then accepting to run an unsigned application. Next time you can run as usual, by just double-clicking on the application.

  2. view3dscene for macOS benefits from latest huge improvements for macOS users in Castle Game Engine. It uses new CGE Cocoa backend (native look, easy build), is packaged to an app bundle etc. Thanks for MacStadium, we now have remote macOS machine available 24/7, for Jenkins and for interactive work, and this allows to build and test view3dscene on macOS forever.

Comments on the forum ➤

Summary of 2nd Open Meeting for CGE Users and Developers, and announcing the 3rd meeting – September 17th

Posted on

Open Meeting - Michalis presentation
Open Meeting - Andrzej presentation

Thank you all for joining on today’s 2nd open meeting!

I am immediately announcing our next meeting, on September 17th. Click here to register on Discord, add it to your calendar etc.

Summary of today’s meeting:

  1. Summary of new/upcoming features:

    1. I talked about new camera/navigation features. On new-cameras branch, very very close to being finished + merged to master 🙂

    2. Andrzej Kilijański talked about new physics features. On physics branch, likewise very close to being finished 🙂

    3. I showed engine on macOS, a recent new feature.

  2. I talked a bit about future:

    1. Stuff from from 2022 plans remains in place. We did some planned things, remaining: modifying materials, new examples/fps_game/, Steam, nodes optimization.

    2. I am doing lots of thinking about our “message to new users”. It comes down to better communication how we’re equal/competitive to other engines (cross-platform, editor, powerful OOP API), but also how we’re special (glTF, X3D, native Pascal) and what advantages come from it. I plan to reorganize our webpage to communicate this.

    3. Easy installers. Snapcraft on Linux. Package with bundled FPC and Lazarus (with Lazarus preconfigured for single window (anchor docking), dark theme).

    4. Automation. We want to provide ready files that will make your projects build by GitHub Actions and GitLab CI.

  3. We talked about a few things:

    1. Code editor (I talked about how we decided to use Lazarus. Although VS Code is also very appealing — but Lazarus’ code tools for Pascal and debugger win)

    2. Kagamma mentioned: a way to assign events inside castle-editor. I did’t find time to address it, but the short answer is: yes!

    3. WebGL (using FPC WebAssembly) port is anticipated by everyone, including me 🙂

Comments on the forum ➤

Huge improvements for macOS users: macOS binary beta release, Cocoa backend for TCastleWindow, automatic running and packing using AppBundle, access to macOS thanks to MacStadium

Posted on

Castle Game Engine editor on macOS
Castle Game Engine editor on macOS
castle-view-image on macOS
view3dscene on macOS - file dialog
view3dscene on macOS - color dialog
view3dscene on macOS
Simple alert on macOS

We have a number of game-changing improvements for macOS users today!

  1. We have Castle Game Engine binary release, for macOS, available to download here. Download it and enjoy! Just unpack the zip and double-click castle-editor inside the bin/ subdirectory.

    UPDATE: due to important bug being fixed, I updated the above link to lead to latest CGE for macOS, not the older version announced at this date.

    Note: You have to still separately install FPC (and some IDE, like Lazarus) e.g. using Lazarus install for macOS or fpcupdeluxe.

    Note: our applications are not (yet) signed. Double-clicking for the first time on castle-editor will result in an unhelpful error. Just right-click on it instead, choose “Open” from the context menu, and then you will be able to confirm that you want to run an unsigned application.

    Soon: This macOS build will be automatically updated by Jenkins, and available prominently on our main page just like other platforms. UPDATE: This is done now 🙂

  2. Your CGE applications now build on macOS without any extra steps, because we have a Cocoa backend in TCastleWindow. It is a fully-featured TCastleWindow backend, that supports:

    Previously our support for macOS was weird — we had only non-optimal options:

    1. you could use X11 or GTK backends, but they don’t look native
    2. you could use LCL backend, with Cocoa underneath, but then compilation was more cumbersome: you needed to open project in Lazarus and change dependency from castle_window to alternative_castle_window_based_on_lcl.

    This is solved now. Our TCastleWindow will just use Cocoa (without the need for LCL in the middle) directly, and the code is simple and the effect is a 100% native look.

    This also means that you can build macOS applications from the build tool, or from CGE editor (using menu item “Compile And Run”, F9), and it just works like on other platforms.

    The Cocoa backend in TCastleWindow was based on

  3. CGE applications now run on macOS using application bundle, which is an Apple invention to “package” an application as a directory like MyApplication.app along with some metadata and conventions (where to place executable, data, icon etc.). This is necessary to make macOS GUI application fully functional, also with main menu.

    When running we create a temporary AppBundle, using symlinks to the actual files (so the process is lighting fast, even if you have large game data, as we will not copy the data — only symlink to the whole data directory).

    This applies to running from CGE editor, or using castle-engine run from the command-line.

  4. Also, CGE applications are packaged to application bundle.

    This applies to packaging from CGE editor, or when using castle-engine package. You can also request the AppBundle format explicitly, using proper CGE editor menu item, or on command-line castle-engine package --package-format=mac-app-bundle.

    App bundles are also used throughout the CGE packaging. castle-editor, view3dscene, castle-view-image are packed by "pack_release.sh" to an app bundle, and they execute each other through a path in the bundle. Custom editor (in case you define project-specific custom components) is likewise run through the app bundle.

  5. File associations now work on macOS as well, thanks to some automatic code from Cocoa backend. Opening the associated file will be reported using TCastleWindow.OnDropFiles.

    The syntax to specify file associations has been changed and extended, to accomodate more options.

    See example manifests how to specify associations in view3dscene, castle-view-image.

  6. By the way of all this, an improvement for all platforms: CGE editor passes now to CGE build tool the detected CGE location. This makes some setups working more reliably, in case your CGE editor can detect CGE location but CGE build tool doesn’t (or would detect a different location).

  7. By the way of all this, TCastleWindow.ColorDialog allows to edit alpha (not only RGB) of the color. Only backends Xlib, Cocoa actually allow user to edit alpha now.

This was all possible thanks to the MacStadium open-source program which provides us now full remote access to a macOS machine. This gives us long-term access to macOS, for the purpose of improving CGE support for macOS and iOS, so we can put work into perfect support and testing for these platforms!

Comments on the forum ➤

Save the date: Next weekend: 2nd Open Meeting for CGE Users and Developers

Posted on

Castle Game Engine editor - sample compilation error

The time is near! Join Michalis Kamburelis and other Castle Game Engine developers, contributors and users at our 2nd meeting on Discord.

The meeting will happen at 15:00 (UTC timezone) on Saturday, 4th June.

Meeting will be on our Discord channel #open_meeting.

Please keep your mic muted when you’re not speaking, to avoid the noise 🙂

Agenda:

  1. Presentation of new/upcoming big CGE features: new camera and navigation features, physics, macOS Cocoa, and more.

  2. Your turn 🙂 I want to invite everyone to showcase what you are working on! I hope to make this a 2-way show, in which everyone interested has time to take the stage and show whatever (s)he wants.

  3. This is also the time for questions. I will be more than happy to answer any questions about the engine — how to do something, what do we plan etc.

Comments on the forum ➤

Big update to “Custom Components” documentation, critical localization fix

Posted on

Custom component in CGE editor

I have extended the Custom Components documentation, to serve as a good overview for people who want to create new components that are registered in CGE editor.

  1. Nicer introduction and consolidates important information from other pages,

  2. Documented publishing classes: using subcomponents, references, observing them using TFreeNotificationObserver

  3. Documented when and why you should use SetTransient

  4. There’s also a description of new TSerializationProcess features: (De)Serializing other values (not just published properties). This is preliminary, i.e. the feature is not yet available on master, only on new-cameras branch.

    TSerializationProcess was extended to allow you to read/write custom instances and simple types (integer, string, boolean, single) and vectors/colors to design file. This allows to

    1. have internal information (not published, may be even private) that is still serialized/deserialized (use-case: storing design-time camera and navigation params in editor),

    2. have backward compatibility for old designs by reading an old property name from file, and converting it to new property immediately. This allows to remove old property names from code, but still support it for file reading.

We also fixed a critical localization bug. And added auto-tests so that the bug will never return 🙂

Comments on the forum ➤

Compositing shaders improvements, “Mountains of Fire” demo updated

Posted on

Mountains of Fire

I have improved the available “plugs” for our compositing shaders mechanism and updated their documentation.

The overall goal was to make them friendly when you target only Phong shading, or want to switch between Phong and Gouraud shading.

  • New PLUG_fragment_modify, simplest way to modify calculation after lighting, textures, fog are applied. This is also used now in the initial examples on Chapter 5. Extending the shaders with plugs.

  • Clear warning when trying to use deprecated PLUG_texture_apply.

  • Improved documentation about new things, and differences between Phong and Gouraud shading — PLUG_main_texture_apply, PLUG_texture_apply, PLUG_lighting_apply all necessarily behave a bit different depending on shading.

I have also updated Mountains of Fire (see also game page) a bit, to use new shader effects.

Comments on the forum ➤

Double click in the output to open code editor

Posted on

Castle Game Engine editor - sample compilation error

Let’s kick-off the weekend with a small but important new feature:

You can now double-click in the Castle Game Engine editor “Output” list to open an editor at auto-detected file, with auto-detected line and column. Great to easily jump to the error message.

  • It can detect various message types — errors, warnings, notes, progress “compiling …” messages.

  • It can find units within your project or even CGE sources. So it’s great for CGE engine development too.

  • Not all editors support opening at particular line/column of the file: only VS Code and (if you specify a specific command in “Preferences”) your custom editor.

    I already submitted a feature request to Lazarus to make it also possible there. You watch it / upvote (“thumbs up”) on GitLab.

    You can configure Emacs as a “custom editor” to handle this: emacs +${LINE}:${COLUMN} ${PAS} (put this as “Open Pascal file at line/column” in preferences).

    You can configure Notepad++ as a “custom editor” to handle this: notepad++ -n${LINE} -c${COLUMN} ${PAS} (put this as “Open Pascal file at line/column” in preferences).

Comments on the forum ➤

Camera and navigation rework almost finished. TODO: This news announcement is too long, we have too much new stuff to announce

Posted on

Camera from Sketchfab in glTF

I’m nearly done with the big amount of changes on new-cameras branch. Below is a draft news announcement that will become official (and more complete) soon!

TODO: This is too long to announce, too many things. And this is not even finished yet, there will be more gains from this in UI.

TODO: Record a movie about this.

New features of camera and navigation:

  1. During design-time (that is, in CGE editor) you use an internal editor camera and navigation to move around the scene, without automatically changing the camera / navigation that will be used later for playing the game.

    This gives you more flexibility in how you move in the world at design-time, and this gives us more flexibility to implement best navigation at design-time, without worrying what is best for run-time.

    In particular

    • Dragging with left mouse button over viewport now doesn’t change camera. This makes it safer to navigate, as you don’t accidentally drag transform when you want to change camera, or vice versa, because now they are tied to different mouse buttons.

    • Navigation at design-time is activated by pressing and holding right mouse button over a viewport. This is consistent with various other game engines.

    • Design-time navigation fly mode shortcuts:

      Change speed by mouse wheel, as well as + and - keys.
      Keep holding right mouse button to rotate using mouse look.
      Nove by ASWD.
      Move down/up by QE.
      
    • Also (Viewport menu):

      Home to view all
      F to focus selected (a bit like in Unity, yes :) )
      
  2. TCastleCamera is now a TCastleTransform descendant, and as such it can be placed on Viewport.Items now.

    The current camera should be assigned to Viewport.Camera.

    In general Viewport.Camera and adding camera to Viewport.Items are independent actions (it was a mess when we tried to make them too much “magically” auto-connected). But

    • for backward-compatibility, camera from old designs is automatically assigned as Viewport.Camera, so old designs just work

    • when creating new viewport from code (but not when deserializing and not at design-time), we add new unnamed camera (as Viewport.Camera, and to Viewport.Items)

    • when creating new viewport in editor (but not when deserializing) we add new named camera (as Viewport.Camera, and to Viewport.Items)

  3. Camera can have children, like any other TCastleTransform.

    This is nice to place something relative to camera, e.g. weapon in typical FPS games.

    It is also new advised way to make a “headlight“. Just add a light, like TCastleDirectionalLight, as camera child. That’s it. Leave Viewport.UseHeadlight as hlOff, or UseHeadlight=hlMainScene (default) and leave Viewport.Items.MainScene=nil (default). We don’t need MainScene, we don’t need UseHeadlight anymore. This way it is also trivial how to control or adjust the headlight. It’s just your component, change it freely to another light, remove it, change the light Exists property etc.

    The default TCastleDirectionalLight direction is -Z, conveniently, as this is also the direction along which the camera is looking at. So just dropping default TCastleDirectionalLight as a TCastleCamera is all you need.

    See examples/viewport_and_scenes/headlight/ for example.

  4. Camera can be a child of some other transformation, e.g. you can mount camera on a car, or attach it to a bone of your skeleton.

  5. You can create TCastleCamera instances, from code or from editor, and have as many as you need. Just set Viewport.Camera to the current camera. You can set this property freely, also to nil (for consistency, it must be prepared for “no camera”, e.g. if you destroy the camera; viewport rendering is not done in this case).

    It also auto-synchronizes Viewport.Items.MainCamera with Viewport.Camera, if they were synchronized already. In simple cases (if you don’t use multiple viewports) Viewport.Items.MainCamera and Viewport.Camera are always synchronized.

  6. We display a preview from selected camera. This way you can reliably move any camera. And you can reliably move things with respect to camera.

    You can pin the preview, make it larger/smaller, to control and display it as necessary.

  7. This also makes the AnimateTo of cameras more useful.

    You can now setup various cameras around the world in editor, and use CurrentCamera.AnimateTo(SomeCamera) to smoothly animate to them.

  8. Adding Navigation components (to use at run-time) is no longer “special”. Just use “Add User Interface -> Navigation/xxx” to insert navigation as child of viewport.

    No more special menu to do that (that was previously trying to do some needless automatic around it, removing/adding it to children, removing previous navigation etc.) Also there’s no longer a need to use TCastleViewport.Navigation. It’s a deprecated property now, that just adds/removes children, nothing more.

    Also Navigation Exists works as expected. You can have multiple navigation components within on TCastleViewport, they can even work “all at once” but in practice (with current navigation classes) you will want to use Exists to make only one of them active.

  9. New property TCastleNavigation.CheckCollisions is also available.

More new features, done BTW:

  1. Editor improvements: Smaller gizmos

  2. Editor improvements: Show whether whole vector/color has modified state properly, e.g. see if Translation value is not bold or not

  3. glTF interpolators with unique names

  4. Inspector on F8 shows modified props (non-default value) more emphasized (blueish background for now)

  5. TCastleVectorXxxPersistent is now a TCastleComponent descendant, it can have owner, it can react to csLoading, it can and should be SetSubComponent(true), it is deserialized better: sets the final vector at once.

Backward compatibility notes:

  1. At the center of this change, is that TCastleCamera is now a TCastleTransform descendant. This generally makes it more powerful (e.g. you can add child objects to camera) but also makes some changes to API:

  2. TCastleCamera no longer stores “initial” vectors. Just like all TCastleTransform, it just stores current position/direction/up, delegating to some other code management of “initial” vs “current” state, if you need that.

  3. TCastleCamera.Position is deprecated. Use now Translation, not Position. Or WorldTranslation to get it in world-coordinates.

  4. TCastleCamera.Update now follows the signature of TCastleTransform.Update, thus it gets extra RemoveType parameter.

  5. TCastleCamera had some specialized GetView / SetView overloads. They have been removed — because they would be confusing now.

    TCastleCamera.GravityUp is always in world space.

    To get/set camera vectors, you should usually use GetWorldView / SetWorldView to operate in world space. The GetView / SetView, defined in TCastleTransform, continue to operate in local space. The new code should usually be updated from GetView / SetView to GetWorldView / SetWorldView — because almost always you want to query/set camera in world coordinates, not in local coordinates. This way you support the case “camera can be a child of something else”.

    So you should usually upgrade this code:

    // OLD
    MainViewport.Camera.GetView(Pos, Dir, Up, GravityUp);
    

    into this:

    // NEW
    MainViewport.Camera.GetWorldView(Pos, Dir, Up);
    GravityUp := MainViewport.Camera.GravityUp;
    

    And this code:

    // OLD
    MainViewport.Camera.SetView(Pos, Dir, Up, GravityUp);
    

    into this:

    // NEW
    MainViewport.Camera.SetWorldView(Pos, Dir, Up);
    MainViewport.Camera.GravityUp := GravityUp;
    
  6. TCastleNavigation had some deprecated GetView, SetView, Position, Direction, Up.

    They have been removed now. You should use Camera.GetWorldView, Camera.SetWorldView in most cases now.

  7. World.CameraXxx deprecated functions have been removed:

    function CameraPosition: TVector3; deprecated 'use MainCamera.Position if MainCamera <> nil';
    function CameraDirection: TVector3; deprecated 'use MainCamera.Direction if MainCamera <> nil';
    function CameraUp: TVector3; deprecated 'use MainCamera.Up if MainCamera <> nil';
    function CameraGravityUp: TVector3; deprecated 'use MainCamera.GravityUp if MainCamera <> nil';
    function CameraKnown: Boolean; deprecated 'use MainCamera <> nil';
    

    Because you should now usually upgrade to MainCamera.GetWorldView or WorldTranslation.
    In general you have to now be aware that camera that world and local coords,
    just like everything other TCastleTransform.

    Same for TCastleSceneCore, removed deprecated:

    function CameraPosition: TVector3; deprecated 'do not access camera properties this way, instead use e.g. Viewport.Camera.Position';
    function CameraDirection: TVector3; deprecated 'do not access camera properties this way, instead use e.g. Viewport.Camera.GetView';
    function CameraUp: TVector3; deprecated 'do not access camera properties this way, instead use e.g. Viewport.Camera.GetView';
    function CameraViewKnown: boolean; deprecated 'do not access camera properties this way, instead use e.g. Viewport.Camera';
    

    Also TCastleViewport.XxxCamera methods that actually talked about navigation (and not Camera) are removed. They have been deprecated for some time, and right now could be quite confusing. So removed:

    RequiredCamera
    WalkCamera
    ExamineCamera
    InternalExamineCamera
    InternalWalkCamera
    ClearCameras
    
  8. The already deprecated methods to auto-create the navigation have moved to separate deprecated class TCastleAutoNavigationViewport. The base TCastleViewport is free from their complication (that turned out to be useless, in most cases).

    This applies to you if you use AutoNavigation, NavigationType, ExamineNavigation, WalkNavigation.

    We advise you to instead create navigation explicitly, in code or in editor, like

    MyWalkNavigation := TCastleWalkNavigation.Create(...);
    Viewport.InsertBack(MyWalkNavigation);
    

    But if you really need automatic management of navigation you can still use TCastleAutoNavigationViewport.

Screenshot using Steampunk Camera by lumoize from Sketchfab.

Comments on the forum ➤

Editor improvements, UI improvements, in-progress Snap packages (Linux packages on any distribution), testing lights and 3D models from Sketchfab

Posted on

Cars from Sketchfab
New cameras and editor improvements
CGE lights and room from Sketchfab
Crypt from Sketchfab
Porshe from Sketchfab

OK, so we have now 3 big things in-progress 🙂

  1. I started to learn Snap packaging. It allows to create packages that work on any Linux distribution and has a connected central store of Snap packages where users can find packages. Both open-source and closed-source packages are allowed there, you can browse existing packages and see there’s a lot of good stuff there. You can always upgrade all your packages using sudo snap refresh. The package release is managed by us (i.e. we will be able to just update CGE there, to any version we want, without waiting for others). Personally, I use it on all my Linux installations now (Debian, Ubuntu, Arch Linux) to manage stuff that for this or that reason is not available in distros’ packages.

    The end result should be that we could tell all Linux users “You can install Castle Game Engine using sudo snap install castle-engine“.

    My current efforts are in view3dscene/snap subdirectory. I.e. I’m learning Snap packaging doing a package for view3dscene.

    Note: there’s also Flatpak with very similar goals. We’ll be looking into it too 🙂 My simple practical reason to target Snap first is that it seems to just have more “market penetration” in my eyes, looking at my apps I just see a number of things that are officially available (and regularly updated) through Snap. Ideally, CGE will be on both Snap and Flatpak 🙂

  2. In the meantime, the work also continues in new-cameras branch. I’m improving now how does the navigation work, we even have a simple key F that works like in Unity — bring to focus the selected 3D/2D thing.

  3. And in the meantime, Andrzej Kilijański works on physics branch. The physics just works cool in the editor now, and it allows us to trivially create new demos. There will be a new 3D and 2D physics demo using the new features.

New features available on master:

  1. Nice colors for class name in editor hierarchy. The component name should “stand out” while the corresponding class name is dimmed.

  2. Hidden the labels displayed over designer when selecting UI items. These labels were often causing more trouble than gain — as they obscured the actual things you were trying to select/move/resize.

  3. Hidden names of subcomponents that you are not really supposed to edit. This applies to subcomponent names, like Perspective subcomponent within a camera.

Moreover, announcing some UI improvements available for a long time now:

  1. TCastleButton.Alignment, TCastleButton.VerticalAlignment.

  2. Safer look of exception messages and inspector invoked by F8. They will look reliably, always the same, regardless of how you customized the UI.

  3. Configurable theme features: TCastleUserInterface.CustomTheme, FallbackTheme, ForceFallbackLook

For this post’s screenshots, I used a few models from Sketchfab. I wanted to test editor on “real” pretty models 🙂

  1. Pony Cartoon by Slava Z.

  2. 1975 Porsche 911 (930) Turbo by Karol Miklas

  3. Abandoned Warehouse РInterior Scene by Aur̩lien Martel

  4. Crypt Location by Bocharova

Comments on the forum (2) ➤