IntuitiveScenarioEditor

This page is obsolete. It should not be relied upon as a source of information. If you are willing and able to update this page, please do so. If it cannot be brought up to date it may be removed.

Reason: It's an GSoC application, and the ideas from it are now either implemented or logged in the issues database. There's a lot about handling WML macros in the editor, which 1.15.4 answered by allowing a separate .cfg file for the hand-edited parts to load the editor-generated .cfg via [scenario]map_file=.

Basics

Hello, you've found my SOC project proposal page. If you want to see the answers to the Wesnoth SOC student questionnaire they are here. This page is mostly a trimmed down version of that (some of it is exactly the same), with some additions to the project proposal section. If you want to know some little facts about me (such as some of my favorite NES games), or to read more in-depth answers, you'll have to go read the questionnaire. Feel free to contact me via email at cjhopman|ATTT|gmail.com

Anyway, my name is Chris Hopman-- I go by cjhopman on irc, forum, etc-- and I am in my third year of my undergraduate studies at the University of Wisconsin - Madison. I am majoring in Computer Science and Mathematics and will be graduating spring '09.

I want to participate in summer of code because it is basically a once in a lifetime opportunity. That is, it is a chance to become a much better programmer, a chance to gain experience working on a real project, a chance to be mentored by an experienced programmer, a chance to become a member of the development team of a great game, a chance to join the community of that great game, a chance to make something that improves that community and that game, a chance to spend a summer doing something I love, and on and on... I mean, it's just an amazing opportunity.

Open Source and Gaming

This section is repeated from my questionairre cjhopman SOC questionnaire

Sadly, I am not currently involved with any open source development projects. However, I have, for a while now, been interested in becoming involved, and my experience with the Wesnoth community in the past few weeks has lit that spark that I needed and I will continue to be involved in open source development, regardless of my involvement in Summer of Code.

Gaming experience
Well… I remember playing the first Mario Bros. on the NES when I was 5. At that same time I started playing computer games, oh were those ever fun. Ever since, I’ve been hooked. Since then, I’ve enjoyed all types of games, but primarily strategy games and role-playing games.

Do I prefer story or gameplay? That's tough, and it depends on the game. For example, the Civilization series all have basically no story, but I love the games. However, almost all RPGs that I enjoy are because of the story, not the gameplay.

What Project and Why

There were several projects that I was interested in – the scenario editor, the map editor, and the formulaAI projects. Of course AI would be fun, but I was interested in the editors as a chance to do a more user-centric project, and to design a GUI. And so, I was more interested in doing one of the editors. In the end I decided primarily on what I thought would be best for the Wesnoth community, the scenario editor. I also considered how much work could reasonably be done on each project in a summer, as I know that many students in past Summer of Code seasons have overscoped there projects and ended the summer with little to show. I think that having an intuitive and well done scenario editor will be a huge benefit to the community, especially if it is written so that it can be extended to be a full campaign editor, including map editing and such. This extension is not feasible to do over the course of the summer, but I absolutely do not plan to let that stop me from doing it afterwards.
There are so many great games that are great precisely because of the community generated content, and the current high-barrier to entry in developing scenarios for Wesnoth is holding back the development of even more such content. Not only that, but Wesnoth itself is basically user-generated content, and it is only fitting to enable the community to more easily contribute.

What do you expect to gain from this project?
Primarily, I expect to become a better programmer. Courses I have taken at my university are great for learning the theory of programming, but I am just as interested in programming well, something that the classes do not teach. For this reason I have done much coding on my own, and often the projects for my classes go well beyond the scope of the assignment – simply because I enjoy programming. However, I am limited by the fact that I don’t know what I don’t know. I can study and read all I want, but the opportunity to work on a project like Wesnoth, with an experienced mentor is priceless.
To think that programming experience is all that I would gain from working on this project is so far from the truth. I will get to become a member of the Wesnoth developer community, to work on a large project with a large team, to spend a summer doing something that I love, to make an important contribution to a great game… I could go on and on.

One of the questions in the questionnaire was what would make me stay in the community after SOC is over. Well, I think a more relevant question is what could make me leave. To be honest, from my (albeit, short) experience with the Wesnoth community, I doubt that you guys will be able to get rid of me. Being a member of the Wesnoth community is such a great opportunity, the opportunity to learn to be a better programmer is primarily what brought me here, but there is much more that keeps me here, and even with the little bit of coding that I have done on the program, I already feel a bit of a responsibility to do more, a bit of an ownership and pride in the code.

Project Proposal

So I plan to write an intuitive scenario editor. In playing with campgen, I believe one of its major drawbacks was its difficulty to use. I will be writing this in C++ for various reasons, primarily because it will allow me to reuse existing, functional code. Also, as most of Wesnoth is done in C++ (as I understand it, almost everything) it just makes sense to not require more dependence on a different language.

As for technical details, I do not intend to reinvent the wheel: that is, I would like to reuse much of Wesnoth’s existing code, for map display, for WML loading and saving, for the GUI I believe that I will primarily use code that is currently being worked on. One major benefit of this (besides the fact that it doesn’t really make sense to rewrite existing functionality), is that the scenario editor will be consistent in look and feel with Wesnoth itself. This makes a huge difference in how professional it appears.

Now, as I have planned this project, it has two important parts: the GUI and the underlying WML system/generator. The plan is to have the underlying WML system to be basically independent of the GUI, and the GUI is precisely what it is meant to be, an interface to that system. This will allow for much better extensibility of the project, and the eventual goal is to have it become an all-in-one editor for campaigns.

As ease of use of the editor is probably the most important part of this project, I will definitely be taking steps to ensure that the goal is met. This will include usability testing at almost every stage of the project. As much as the design may seem to me, and even to other developers, it must also be intuitive for everybody else. The best way to do this will be by having users test this. I will not only have general users test this, I will make friends of mine test it in person, being able to see how they use it and what parts they stumble on will be invaluable.

A little more in-depth discussion...

Now, as a disclaimer, I will admit that I have not designed a scenario on my own, so I may say something that sounds dumb here... Well, that is precisely what the next couple weeks before coding begins are meant to clean up. So, please continue.

So, absolutely the most important thing about this is that it is easy to use. If it's not easy to use then there wouldn't really be much incentive to use it over just doing it by hand. However, without giving the user access to the underlying WML it is unreasonable to expect the editor to be very powerful-- that is, there is too much power in WML to completely abstract away. Ideally this project will provide a very easy interface to do the most common things, that is it would make it very easy to make simple scenarios, and in fact should make it very easy to make even moderately more complex scenarios. Up to that stage it should not require any knowledge of WML. An example of a scenario that would be able to be created easily without knowledge of WML would be The Siege of Barag Gor in SotBE. In fact, you should be able to make something slightly more complicated than that.

To make it so that it is easy to do more advanced things with knowledge of WML, I plan to have a text box for most dialogs that shows the WML that would be generated for the relevant thing (i.e. Event, Unit, etc.) and allow the user to directly edit it in the editor. If the user edits something that the editor recognizes, it should update its own corresponding fields... i.e. if the user changes a location it should update where they would normally have the location. This text box would be optional, in that only people who want to see the underlying WML, need to. Ideally, the text box would also have syntax highlighting, but I don't know how realistic that is, it is something that I would discuss with the mentor, maybe integrating some other project into the editor...

The main part of the user interface would be a map of the scenario. It should be very obvious and very easy for the user to add the most common things to the map... that is units, events(occuring at a particular location), etc. Selection of these items should bring up a dialog-- not so much a popup, think more like how when you select a unit in game it shows the information in the bar, but with a wider bar and with options on it-- that would then have the common options right there, for example a unit's name, traits, side, etc. As I hinted just now, I would like to not only reuse a lot of the existing display code (the map display code, etc...) I would also like to reuse the basic ui layout. Not only would these keep the project consistent with the main game, but it would also be easier for users to learn.

The importation of WML would be a very useful feature, at least the importation of WML that the editor recognizes -- and then the ability to save changes without breaking things that the editor doesn't recognize. Considering the fact that I intend to allow editing of the WML directly through the editor, I don't believe that this will be too difficult. Also, the existing code will provide a lot of the functionality needed to handle importation. The most difficult consideration will be importing things that the editor doesn't recognize, making various changes, and then saving without it breaking the WML, but this will not be an insurmountable challenge.

Exporting WML should be very easy with the design that I envision. Since we will already be basically generating WML for various things on the fly, it will be a matter of combining these together correctly, and a lot of what is needed for that is already present in the current Wesnoth code, I believe.

The final and definitely not least part, of the project is documentation. Now, I intend for a user to be able to use the scenario editor with absolutely no need for external documentation. I believe that if presented correctly it will be intuitive enough how to build a scenario. However, even if I believe that what I build is very easy to figure out, that doesn't really mean much because I know exactly how the thing works. So, for the user, there should be helpful, but non-intrusive documentation in the editor, for example little tooltips that appear in the bottom right as you mouse over things. Also, it will be important to have a detailed online documentation and tutorial, likely walking a user through the creation of a scenario from start to finish.

Extensibility

The eventual goal of my project is to be basically an all-in-one campaign editor. That is it would be able to take you from designing units and maps to build entire campaigns. With this goal in mind from the outset, I will be making design decisions that allow for easily extending the functionality of the editor. In fact, since I see myself likely to be working on extending the project myself, I will be very careful to make that easy to do (then I get to look like a hero when I do it quickly and well).

Preliminary Timeline

March 26 Submit Application and build wiki page on www.wesnoth.org
March 26 – April 11 Continue minor coding tasks on wesnoth, mostly in areas dealing with WML to get an intimate knowledge of the WML processing.
Also, provide further proposal details as requested.
April 14 Accepted to work on Wesnoth for Summer of Code :)
April 14 – May 26 Three goals for this period:

1. Become very familiar with WML, and the design of scenarios. Use this research to refine and improve the project plan.

2. Do some coding work on the Wesnoth GUI, likely assisting Mordante by implement various features.

3. Become more familiar with Python. This will mostly be done in class, though I will also be studying it outside of class. Also, this is not as important as the other two as it is not directly required for the scenario editor. It will, however, allow me to become more familiar with other parts of the Wesnoth code.

Basically, by the end of this period I should be very well-prepared to begin the project. I will also in this period have started some of the groundwork for the project.

May 26 Google Summer of Code begins.

   Begin coding.

Tentative coding schedule: I’ve put some specific functionality goals here, though these are highly likely to change based on input from developers, scenario designers, and Wesnoth players gathered in the weeks prior. Also, I have tried hard to under-scope each iteration, as again, over-scoping is a common mistake for Summer of Code students. My project proposal, however, is very extensible, and so nothing is lost by this under-scoping as there are many more features that can be added. It is very important that at the end of the summer there is a well-done, completed project. I expect that at each of these dates there will be significantly more done than is on the timeline and communication will be important as the summer goes on.

June 9 Iteration 1: Editor is fairly simple at this point, but can display map, add units to different sides, and change different attributes of those units.

June 23 Iteration 2:

   Can Add events triggered at particular locations, or by particular units (either 
       that unit does something, or something is done to it… i.e. unit dies).
   Can edit side info
   Can Edit objectives

July 7 Iteration 3:

   Can save to WML.
   Can load from WML, those features that the editor supports.
   Added a WML editing box for most dialogs (i.e. can write your own WML for events.)
   Maintains WML output that can be edited within editor.
   At this point should be able to fully create basic scenarios.

July 21 Iteration 4:

   Continue to improve functionality
   Make common tasks easy to do, for example, conversations.
   Add more functionality as determined by discussions with users/ designers
   Add story editing

August 4 Iteration 5:

   Add support for more advanced WML
   If ahead of schedule, add advanced unit editing.
   Add more functionality as determined by discussions with users/ designers
   Thorough re-testing of all code has begun.

August 4 Tentative feature lock.

August 4 – 11

   Test and clean code.
   Improve usability and polish in-game documentation.
   Improve code documentation.
   Improve online documentation.

August 11 – 18 Final Week.

   Finalize code.
   Finish code documentation.
   Finish online documentation.

August 18 - ? Continue working on Wesnoth, both extending the finished project and working on other areas of interest.

Further Discussion

So, this is the spot to find information about my developing ideas. I thought I'd consolidate further information here so that finding it doesn't require digging through all that other stuff. Also, the following stuff is quite likely to evolve as I discuss my ideas with other developers.

I think I will add date/time info to these entries so that it's easier to find new stuff for anybody reading this. This means that the entries may not flow as best that they can, but oh well, gotta make sacrifices somewhere.

April 1, ~ 7:20 UTC

The first challenge that I have been considering is that of importing/exporting WML. Now, it is going to be relatively simple to export a scenario made by the editor, the real challenge is to import a hand-written scenario, make changes, and then export it without destroying it. That is, a naive import/export would simply expand all the macros while importing, and it would drop the comments, and then when exported you would have no macros or comments. This would not be a sufficient implementation.

The solutions that I have considered for these problems are slightly different. So, let's consider the problem of maintaining comments first. I think that the easiest, and possibly the best, solution to this problem would be to basically "attach" comments to nearby elements. That is if a comment immediately precedes a given tag, then "attach" it to that tag, and when exporting it will again immediately precede that tag. This would require defining the specific rules for attaching a comment to something. An easy way to do this would be to basically add a common attribute to every tag to hold the comment for that tag, this would be fairly easy to implement, but then comments would only be able to be attached to tags. Ideally, comments would be "attachable" to most WML elements. Clearly, I am still working out how exactly I would implement this.

Now onto the second problem, not destroying macros on importing. I've been considering some possible ways to do this relatively easily. The first would go something like this: export the file naively, then run the preprocessor over the original file, compare the two to find differences, and then re-export the file updating only the areas that change. This seems like a rather brutish way of doing things, and I don't know that I like it. Another implementation would be for the editor to simply keep track of what it changes, and then to, when exporting, only update those things that it changes. This has the disadvantage that it may expand some macros that it doesn't need to.

In addition to the second problem, it will be important to know how the editor will handle some other WML things. So, a quick discussion of things that I have been thinking about. One thing that will help prevent the editor from exporting expanded macros would be for it to recognize and use some macros itself. In particular, I think that the editor should recognize and use most of the core WML macros (that is those found at [[1]]). This would also give a good set of basic functionality for the editor, in that most of these macros are things that the user should be able to change without knowledge of WML.

And, a bit more about handling of WML macros. First, I think in the in-editor text-editor, it would be nice to by default have macros not be expanded, but to have a simple checkbox or something similar that would make the editor expand the macros. This may require the editor to maintain a library of defined macros, which could also be useful elsewhere.

So, that's it for now...

My Contributions to Wesnoth

My first patch submitted [[2]]

This seemed like an ugly hack. So I went to the underlying problem, the unit_map. And that led to my second patch [[3]] which was checked in revision number 25134.

A quick patch I wrote while I got myself a bit more acquainted with the WML preprocessor [[4]]

Bug fix [[5]]

Went back and made some significant improvements to the unit map [[6]]

Implemented a history feature for the new gui [[7]]