[Freeciv-Dev] Re: (PR#7245) Freeciv Tutorial

["Jason Short" <jdorje@xxxxxxxxxxxxxxxxxxxxx>]

<URL: http://rt.freeciv.org/Ticket/Display.html?id=7245 >

Bartosz Kosiorek wrote:

> PLEASE !!!!!!!!!
> Could You create some ingame Tutorial..

This has been requested numerous times before.  It's been discussed but 
nothing's ever been done about it.

Here's a sample tutorial patch.  Under this patch we set up a given 
number of tutorial "events" and assign each of them a message.  The 
first time the event occurrs the message will be shown, and will be 
marked not to be shown again.  The whole thing is implemented 
client-side.  The tutorial messages are put directly into the code.

This is a far sight better than nothing.  But it does have some issues:

- It's not easy to add new events.  Each new event must be coded 
directly into the client somewhere (usually packhand.c) before a message 
for it can be written.  And some events I could imagine (like "second 
turn", "third turn", etc.) will be pretty ugly to code.

- The tutorial isn't tied to the ruleset at all.  Since it's 
client-side, there's no way to have it vary by ruleset or to be specific 
to a particular scenario.

The second problem could be fixed by putting the messages into the 
ruleset and having them be sent server->client.  This would take a fair 
amount of work and may not be worth it, but it's straightforward.

But the first problem is harder.  We can't easily tie the events to game 
events, since many of them require more logic (there's no game event for 
"settlers activated" or "settlers move onto a good location for a new 
city").  We could make tutorial events into game events - generated by 
the server and sent to the client.  This would help a bit since many 
tutorial events could easily be game events ("start of game").  But this 
involves changing lots of code for limited benefit.

jason

/****************************************************************************
 Freeciv - Copyright (C) 2003 - The Freeciv Project
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2, or (at your option)
   any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.
****************************************************************************/

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include "fcintl.h"

#include "dialogs_g.h"

#include "tutorial.h"

struct tutorial_data {
  enum tutorial_event event;
  const char *name;
  const char *title;
  const char *message;
  bool activated;
};

#define ENTRY(name, title, message) \
  {TUTORIAL_ ## name, #name, title, message, FALSE}

struct tutorial_data tutorial[] = {
  ENTRY(START_GAME,
        N_("The game has started."),
        N_("Welcome to Freeciv!  Your goal is to build a civilization to\n"
           "take over the world.  But first you have to start small.")),
  ENTRY(SETTLERS_ACTIVATED,
        N_("These is a settler unit."),
        N_("This unit can be used to build cities.  Your first task should\n"
           "be to find a good location for a city and build one.  Move the\n"
           "settlers onto some clear terrain (preferably near water) and\n"
           "press 'b' to found the city.")),
  ENTRY(EXPLORER_ACTIVATED,
        N_("This unit can be used to explore."),
        N_("You should probably use this unit to explore nearby territory.\n"
           "You may press 'x' to set it to auto-explore mode, or move it\n"
           "around manually to investigate areas that interest you."))
};

/****************************************************************************
  Load the tutorial information from the section file.
****************************************************************************/
void load_user_tutorial_options(struct section_file *file)
{
  int i;

  for (i = 0; i < ARRAY_SIZE(tutorial); i++) {
    tutorial[i].activated
      = secfile_lookup_bool_default(file, FALSE, "tutorial.%s",
                                    tutorial[i].name);
    tutorial[i].activated = FALSE;
  }
}

/****************************************************************************
  Save the tutorial information to the section file.
****************************************************************************/
void save_user_tutorial_options(struct section_file *file)
{
  int i;

  for (i = 0; i < ARRAY_SIZE(tutorial); i++) {
    secfile_insert_bool(file, tutorial[i].activated, "tutorial.%s",
                        tutorial[i].name);
  }
}

/****************************************************************************
  Activate the tutorial event (assuming it hasn't already been activated).
****************************************************************************/
void tutorial_event(enum tutorial_event event)
{
  int i;

  /* This loop is inefficient, but that's okay. */
  for (i = 0; i < ARRAY_SIZE(tutorial); i++) {
    if (tutorial[i].event == event && !tutorial[i].activated) {
      popup_notify_dialog(_("Tutorial"), _(tutorial[i].title),
                          _(tutorial[i].message));
      tutorial[i].activated = TRUE;
    }
  }
}

/****************************************************************************
 Freeciv - Copyright (C) 2003 - The Freeciv Project
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2, or (at your option)
   any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.
****************************************************************************/

#ifndef FC__TUTORIAL_H
#define FC__TUTORIAL_H

#include "registry.h"

enum tutorial_event {
  TUTORIAL_START_GAME,
  TUTORIAL_SETTLERS_ACTIVATED,
  TUTORIAL_EXPLORER_ACTIVATED,
  TUTORIAL_MILITARY_ACTIVATED,
  TUTORIAL_DIPLOMAT_ACTIVATED,
  TUTORIAL_CARAVAN_ACTIVATED,
  TUTORIAL_LAST
};

void load_user_tutorial_options(struct section_file *file);
void save_user_tutorial_options(struct section_file *file);
void tutorial_event(enum tutorial_event event);

#endif /* FC__TUTORIAL_H */

? client/tutorial.c
? client/tutorial.h
Index: client/Makefile.am
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/Makefile.am,v
retrieving revision 1.53
diff -u -r1.53 Makefile.am
--- client/Makefile.am  2003/12/06 19:23:50     1.53
+++ client/Makefile.am  2004/01/16 18:36:08
@@ -174,6 +174,8 @@
        repodlgs_common.h \
        tilespec.c      \
        tilespec.h      \
+       tutorial.c      \
+       tutorial.h      \
        audio.c         \
        audio.h         \
        audio_none.c    \
Index: client/control.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/control.c,v
retrieving revision 1.123
diff -u -r1.123 control.c
--- client/control.c    2004/01/09 16:59:50     1.123
+++ client/control.c    2004/01/16 18:36:08
@@ -38,6 +38,7 @@
 #include "menu_g.h"
 #include "options.h"
 #include "tilespec.h"
+#include "tutorial.h"
 
 #include "control.h"
 
@@ -134,6 +135,18 @@
       punit->ai.control = FALSE;
       refresh_unit_city_dialogs(punit);
       request_new_unit_activity(punit, ACTIVITY_IDLE);
+    }
+
+    if (unit_flag(punit, F_CITIES)) {
+      tutorial_event(TUTORIAL_SETTLERS_ACTIVATED);
+    } else if (unit_flag(punit, F_DIPLOMAT)) {
+      tutorial_event(TUTORIAL_DIPLOMAT_ACTIVATED);
+    } else if (unit_flag(punit, F_HELP_WONDER)) {
+      tutorial_event(TUTORIAL_CARAVAN_ACTIVATED);
+    } else if (is_military_unit(punit)) {
+      tutorial_event(TUTORIAL_MILITARY_ACTIVATED);
+    } else {
+      tutorial_event(TUTORIAL_EXPLORER_ACTIVATED);
     }
   }
   
Index: client/options.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/options.c,v
retrieving revision 1.89
diff -u -r1.89 options.c
--- client/options.c    2004/01/11 17:45:03     1.89
+++ client/options.c    2004/01/16 18:36:08
@@ -38,6 +38,7 @@
 #include "clinet.h"
 #include "cma_fec.h"
 #include "tilespec.h"
+#include "tutorial.h"
 
 #include "options.h"
  
@@ -490,6 +491,8 @@
   for (i = num - 1; i >= 0; i--) {
     load_cma_preset(&sf, i);
   }
+
+  load_user_tutorial_options(&sf);
  
   section_file_free(&sf);
 }
@@ -600,6 +603,8 @@
     save_cma_preset(&sf, cmafec_preset_get_descr(i),
                    cmafec_preset_get_parameter(i), i);
   }
+
+  save_user_tutorial_options(&sf);
 
   /* save to disk */
   if (!section_file_save(&sf, name, 0)) {
Index: client/packhand.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/packhand.c,v
retrieving revision 1.343
diff -u -r1.343 packhand.c
--- client/packhand.c   2004/01/11 17:45:03     1.343
+++ client/packhand.c   2004/01/16 18:36:09
@@ -67,6 +67,7 @@
 #include "repodlgs_g.h"
 #include "spaceshipdlg_g.h"
 #include "tilespec.h"
+#include "tutorial.h"
 #include "wldlg_g.h"
 
 #include "packhand.h"
@@ -337,6 +338,8 @@
     
     free_intro_radar_sprites();
     agents_game_start();
+
+    tutorial_event(TUTORIAL_START_GAME);
   }
 
   if (get_client_state() == CLIENT_GAME_OVER_STATE) {
Index: client/include/dialogs_g.h
===================================================================
RCS file: /home/freeciv/CVS/freeciv/client/include/dialogs_g.h,v
retrieving revision 1.13
diff -u -r1.13 dialogs_g.h
--- client/include/dialogs_g.h  2003/11/28 17:37:20     1.13
+++ client/include/dialogs_g.h  2004/01/16 18:36:09
@@ -13,6 +13,7 @@
 #ifndef FC__DIALOGS_G_H
 #define FC__DIALOGS_G_H
 
+#include "nation.h"            /* Nation_Type_id type */
 #include "shared.h"            /* bool type */
 #include "terrain.h"           /* enum tile_special_type */