Add project template without default state

[and3md]

As with folders, we need a template without creating a default state. I think it's hard to come up with a name for the state that will be appropriate. Requiring the user to "clean up" an empty project right after creating it, in my opinion, means that we need a really empty project template. Such a template would definitely be useful for tutorials and advanced users. Perhaps not a separate template, but an option displayed when creating or selecting Empty template.

How many things user need do presents 4.1 Section of tutorial. I think that it can be deleted if we add such template or option to not create default state.

[and3md]

Another option is to add the option to type a state name when creating the project.

[michaliskambi]

I'm thinking :)

1. Adding new state (with Pascal code, including lines to initialize it, and connected state file in data/) is somewhat harder to make, but we want to do it anyway.

2. Asking user for the "state name" at creation of "empty" project is much easier to implement, but then it would be an exceptional behavior for "empty" project. As other templates like "3D game" have 2 states, so the question would not make sense there.

So... I want to do 1. I'll do it ASAP.

[michaliskambi]

Adding new units, with optional new state, is almost finished on https://github.com/castle-engine/castle-engine/tree/new-code-features-in-editor branch. I will let here know when it is finished :)

Note that it will address only 1 half of this issue ("adding new state").

It will not address the other half ("we want to remove the main state added initially"). Right now, I hesitate how/if to address it.

• Adding "template without main state"? I admit I do not like it, because it would be confusing to new user that doesn't know that "the first action I should do now is to create new state".

• Asking at "empty" template for state name? Maybe this is the least amount of work. But it makes an exception for "empty" template.

• Adding a "Remove state" menu? Possible now (the magic comments I add in https://github.com/castle-engine/castle-engine/tree/new-code-features-in-editor allow this) but a lot of additional work.

• Do nothing at engine level? Tutorial should use "main" state just for main menu and keep it simple?

[michaliskambi]

Adding new units (including adding new states) is now merged into CGE master.

This is the draft news announcing them (not publicly announced yet; I may decide to first go with TUIState rename, and then actually update all examples; for now only 4 templates are actually updated to follow new conventions mentioned below):

""""

New Code options in the editor:

Menu "Code":

• Open Project in Lazarus
• Edit Unit... (choose unit by dialog box)
• Edit Unit Associated With Design (F12, searches for unit with same basename as current design but extension .pas)
• New Unit
  • Empty
  • With Class
  • With State (it can even automatically add the state initialization!)

Most of the new options are rather straightforward, but 2 require following certain conventions to make them work. You may want to adjust your existing projects to follow these conventions (nothing bad happens if you don't, these conventions are only necessary to allow editor to perform these operations automatically; they have 0 effect on the actual running game code):

1. The option "Edit Unit Associated With Design" assumes that the filenames of Pascal units and designs match. That is, for design file like "xxx.castle-user-interface" it just searches for Pascal unit called "xxx.pas" (using search paths from CastleEngineManifest.xml). This means that e.g. using it with "state_main_menu.castle-user-interface" design file will not automatically find "gamestatemainmenu.pas" unit -- we recommend you to rename your state file.

   (We accept also .pp extension, and unit name may be lowercase or CamelCase. But lowercase is advised as more reliable on case-sensitive filesystems. This follows FPC / Lazarus.)

2. Adding new state to the initialization requires that one of the units (listed on game_units, reachable using search paths from CastleEngineManifest.xml) has special comments:

   { CASTLE-INITIALIZATION-USES-BEGIN }
   { CASTLE-INITIALIZATION-USES-END }
   { CASTLE-STATE-CREATE-BEGIN }
   { CASTLE-STATE-CREATE-END }

   The first pair delimits state units declaration in the uses clause, and may look like this:

uses SysUtils,
  CastleWindow,
  { CASTLE-INITIALIZATION-USES-BEGIN }
  // The content here may be automatically updated by CGE editor.
  , GameStateMenu
  , GameStatePlay
  { CASTLE-INITIALIZATION-USES-END };

The second pair delimits state creation lines (typically in Application.OnInitialize call) and may look like:

  { CASTLE-STATE-CREATE-BEGIN }
  // The content here may be automatically updated by CGE editor.
  StatePlay := TStatePlay.Create(Application);
  StateMenu := TStateMenu.Create(Application);
  { CASTLE-STATE-CREATE-END }

Of course all our templates/examples have been updated to follow these conventions.
"""

[michaliskambi]

Thinking about how to simplify the notion "we want to remove the main state added initially" in tutorial:

I'm leaning toward doing nothing in CGE about it for now. I have here some ideas, but they either feel incomplete/inconsistent in some way (asking user for new state name at "empty" template) or would be a lot of work just for this simple thing (window to "remove states" or "rename states" etc.).

My proposition to simplify this part of the tutorial:

1. Just use the state "main" for the main menu. Don't try to fight with it :)

2. Or add state "mainmenu" (by new editor feature) and remove state "main" manually (just remove 2 files, and manually remove 2 lines in gameinitialize.pas, and remember to update the line setting initial state TUIState.Current := ....).

Unassigning myself. Hopefully what I did now is enough :) I'm leaving the issue open for @eugeneloza to update the tutorial text to simplify it, using latest CGE advancements :)

[and3md]

@michaliskambi I'm still thinking about that. And I think we understand the name "Empty" differently - for me it's an "Empty project" (so the presence of the state is a little surprise), and for you (in my opnion) it's an "Empty state" - project with one empty state. When I realized it, I see two new possible solutions:

1. Remove "Empty" and add two templates: "Empty project" and "Empty state"/"Empty with state"/"Project with empty state"/"One state"
2. Treat "Empty" as "Empty project" and remove state from it because now that we have such an easy way to create new states. We can also change project window in editor to have a button "create state" and more hints for new comers when no design is loaded.

[michaliskambi]

I have a problem with AD 1 and AD 2 admittedly -- because they create a project that is a non-obvious for a newcomer. Having a version of a project without any state means that a new person may struggle "what do I do with this", not knowing that the most advised sensible way forward is to click "New Unit With State" and we didn't show it just because we didn't know if the name main suits you.

I guess it's because I treat existing templates not only as "good starting points" but also "suitable points to start learning about the engine". I see the problem with trying here to "hit 2 birds with one stone"... but I'm not ready to resign from this. I mean, people will use this approach when trying to learn the engine ("I will not read documentation, however good it is, let me first just try clicking around in this editor and see what I can do."). New Unity projects also generally come with some scene (or maybe they open an unsaved scene by default?).

[and3md]

OK, another idea: So maybe when creating a new empty project, immediately pop up the Create new state window. In this way, we will have an influence on the name, and the user will learn how to create states.

I also believe that a user who wants to learn the engine will start with a 2d or 3d game template.

BTW. I also think that on editor main window we should add "Open example" button with easy way to open examples (list of them). Documentation/Tutorials link also should be there. I think that would be a greater convenience for newcomers than templates.

[and3md]

Maybe the lack of "Open examples" makes you hesitant about templates. ;)

[michaliskambi]

Displaying the "Create new state" doesn't feel like best solution -- as we'd need a popup without "cancel" button, which is bad UX :)

"Open examples" is something we want, but this opens another large set of questions :) We'd like to show anyway 4 most basic examples (empty, 3d, 2d etc.) :) and allow user to use them as a starting point -- which means that difference "templates" vs "basic examples" is blurred anyway.

I'm leaning now most toward a special edit box "Name of new state" for "Empty".

[michaliskambi]

special edit box "Name of new state" for "Empty".

Done! @and3md convinced me this is an important feature :) The "Main State Name" is now configurable in the "New Project" window for "Empty" and "3D model viewer" templates ("3D model viewer" configurability is just an extra).

[michaliskambi]

Unassigning myself, leaving open so that @eugeneloza can hopefully now remove a lot of tutorial text :) Just create a "New Project" and it should be in a much more ready-to-use-state now.