{"id":3789,"date":"2022-11-26T14:00:46","date_gmt":"2022-11-26T14:00:46","guid":{"rendered":"https:\/\/castle-engine.io\/wp\/?p=3789"},"modified":"2022-11-28T03:50:47","modified_gmt":"2022-11-28T03:50:47","slug":"documentation-enhancements-using-children-components-api-and-code-conventions-about-memory-management-nils-beforedestruction-and-more","status":"publish","type":"post","link":"https:\/\/castle-engine.io\/wp\/2022\/11\/26\/documentation-enhancements-using-children-components-api-and-code-conventions-about-memory-management-nils-beforedestruction-and-more\/","title":{"rendered":"Documentation enhancements: using children components, API and code conventions about memory management, nils, BeforeDestruction and more"},"content":{"rendered":"
\n \"Raspberry<\/a><\/td><\/tr><\/table>\n

We have a number of enhancements to our 2 large documentation pages (targeting mostly advanced engine users \/ developers):<\/p>\n

    \n
  1. \n Custom Components<\/a> documentation was extended with description how do we advise to create children components in your custom components. This is useful when you want to create a new component, register it in CGE editor<\/a>, and you want to use existing components as children.<\/p>\n
      \n
    1. \n

      You can have internal children (using SetTransient<\/code>).<\/a><\/p>\n

    2. \n

      You can create regular components in OnCreate<\/code> method that the user can later completely change and even remove (free).<\/a><\/p>\n

    3. \n

      You can have subcomponents (where user can configure properties, but shouldn’t free \/ assign a different instance).<\/a>\n <\/ol>\n

      All cases are documented with example code.<\/p>\n

    4. \n

      We have a big Coding Conventions<\/a> page that documents a lot of low-level and high-level guidelines about how the engine is developed. It starts with some mundane stuff (like indentation — 2 spaces, never tabs!) but later discussed more interesting topics that I recommend to read:<\/p>\n

        \n
      1. \n

        Our guidelines for BeforeDestruction<\/code> usage<\/a>. Big thanks for Andrzej Kilija\u0144ski<\/i> for talking it over with me — it’s a very powerful mechanism when combined with clear guidelines when to use it.<\/p>\n

      2. \n

        You can (and should) free the things you allocated; you should never free other things, unless explicitly allowed<\/a>.<\/p>\n

      3. \n

        What can be nil<\/a>.<\/p>\n

      4. \n

        Declarative API (classes with independent properties) is simple to use<\/a>.<\/p>\n

      5. \n

        Optimize smartly: profile, optimize where it matters (and not where it doesn\u2019t), think about smarter algorithms and moving CPU work to GPU to get big benefits<\/a>.<\/p>\n

      6. \n

        Fix warnings (let the compiler help you write reliable code)<\/a>. (Shining example: recent critical TCastleThirdPersonNavigation fix for seemingly-random bug<\/a>.)<\/p>\n

      7. \n

        Be consistent in API design<\/a>.<\/p>\n

      8. \n

        Backward compatibility is important; having a consistent (easy to learn) API and useful features is even more important<\/a>.\n <\/ol>\n<\/ol>\n

        This post’s image follows our tradition if there’s no clear image to illustrate this, just search for any pretty 3D model<\/i>. It turns out that if you search for “documentation”<\/i> on Sketchfab, one of the things that comes up are 3D models of Raspberry Pi<\/a>, which we love and support in CGE (both as a platform where you can work, and as a platform to which you can compile your games). So here’s a screenshot of CGE editor rendering a 3D model of Raspberry Pi Pico<\/a> by abdou bouam<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"

        We have a number of enhancements to our 2 large documentation pages (targeting mostly advanced engine users \/ developers): Custom Components documentation was extended with description how do we advise to create children components in your custom components. This is useful when you want to create a new component, register it in CGE editor, and … <\/p>\n

        Continue reading \u27a4 “Documentation enhancements: using children components, API and code conventions about memory management, nils, BeforeDestruction and more”<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":3800,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"publish_to_discourse":"0","publish_post_category":"9","wpdc_auto_publish_overridden":"1","wpdc_topic_tags":"","wpdc_pin_topic":"","wpdc_pin_until":"","discourse_post_id":"2308","discourse_permalink":"https:\/\/forum.castle-engine.io\/t\/documentation-enhancements-using-children-components-api-and-code-conventions-about-memory-management-nils-beforedestruction-and-more\/685","wpdc_publishing_response":"","wpdc_publishing_error":"","jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[1],"tags":[],"class_list":["post-3789","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-uncategorized"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"https:\/\/castle-engine.io\/wp\/wp-content\/uploads\/2022\/11\/Zrzut-ekranu-z-2022-11-26-02-52-46.png","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p9IgYW-Z7","jetpack_likes_enabled":false,"_links":{"self":[{"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/posts\/3789","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/comments?post=3789"}],"version-history":[{"count":15,"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/posts\/3789\/revisions"}],"predecessor-version":[{"id":3820,"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/posts\/3789\/revisions\/3820"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/media\/3800"}],"wp:attachment":[{"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/media?parent=3789"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/categories?post=3789"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/castle-engine.io\/wp\/wp-json\/wp\/v2\/tags?post=3789"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}