Zeriab's Scripting Contest '07

Zeriab's Scripting Contest '07

Motivation
I have not seen many scripting contests lately so I thought it was about time for one.
The goals with this contest are:

• Make scripters more skilled with mouse handling.
• Create tools that ease the development of mouse-interactive systems.
• Create awareness of the area.
• Help scripters improve. (Hence certain elaborations)

Contest Description
This contest is about creating a tool for managing mouse clicks and letting corresponding view(s) be triggered.
This contest is not about creating a mouse module that finds information about mouse positions and other low-level functionality. You should not need to touch WinAPI
This contest is about creating a higher level tool. You can create a mouse module yourself if you want. It is not necessary and there are fine modules out there doing this for you, but if you really want to create one in addition you are welcome.

Make the tool use this interface when getting cursor coordinates:

Code: [Select]

Mouse.x  #Retrieves the mouse's x-position relative to the game window's top-left corner.
Mouse.y  #Retrieves the mouse's y-position relative to the game window's top-left corner.

Is this not how you use your mouse module of choice?
The solution is to write an adapter:

Code: [Select]

module Mouse
  def self.x
    # Code to retrieve the x-coordinate here
  end

  def self.y
    # Code to retrieve the y-coordinate here
  end
end


When creating the register view mechanism you should spend some time considering which data structure you will use. Prioritizing views is not a trivial matter.
You should consider how you will structure the click-detection. That is, where to put which parts of the system. In which classes/objects.

Read the Functional Requirements for what precisely your tool must do. As long as the requirements are fulfilled the tool can be created in any way you like.
A possible usage example for its use is provided below. It is important to notice that this is not THE way this tool will be used. It is an example of how the tool could be used.

Spoiler for Possible usage example:

An excerpt with the interesting parts of a new scene using the tool:

Code: [Select]

class Scene_MyScene
  def main
    # Creates a couple of views
    @my_view = My_View.new
    @my_view2 = My_View2.new
    @my_view3 = My_View3.new
   
    # Sets controllers for two of the views.
    @my_view.controller = My_Controller.new
    @my_view3.controller = My_Controller3.new
   
    # ...
  end

  def update
    # tell the tool to update
    # have normal update as well
  end
end

It would be nice if you can create views that will add themselves to the tool.
The views could be subclasses of Window or Window_Base providing any functionality required by the tool.
The functionality when clicking on a view will in this case be provided by a separate controller class which the view has an attribute.
When the tool is updated it should take care of detecting if any view has been clicked upon and give the controller sufficient information needed for the user-appointed functionality. What exactly the tool provides is up to you.
It is important to notice that this is an example of how the tool could be used. It does not have to work in the way shown in this example. The reason it is here is to help you get started should you have start up problems.
Notice that the implied design choices in this example might not be good design choices. Analyze to what you think is the best solution.

Functional Requirements
There are certain requirements your tool must fulfill for your team to be eligible for the prizes. These are the requirements where the keyword "shall" is used. The "should" requirements give a bonus, but are not required. You might get a review even if your tool does not fulfill all the "shall" requirements.

• The tool shall provide the ability to register views at runtime.
• The tool shall provide the functionality for clicking on registered views - The intention of this tool. You must be able to 'click' on a view. The functionality for finding which view is clicked is on the burden of this tool.
  
  • The tool shall be deterministic when finding which view is registered - In a specific situation clicking on the same x- and y-coordinate will always find the same view.
  • The tool shall support changes in which view is on-top - If you have two views overlapping you must be able to change which view is on top of the other.
  • The tool should support priorities and always-on-top features for views.
• The tool shall support user defined functionality attached to views - What happens when you click on a view.
• The tool shall provide the ability to remove registered views - It could for example be to remove views not in use anymore
• The tool should decouple the user defined function from the tool - You should not have to modify the tool to define functionality and attach them to views.
  

.

What to submit
Script
Place the whole system in one plain-text file.
Creating a simply plug'n'play the script is preferable. In other words: You can just copy the script in the text file and paste it into the script editor. It is then ready to use.

Demo
Make a demo where you have the tool set up and working with a few sample views for demonstrating how your tool can work.

Documentation
Read about Software Documentation here: http://en.wikipedia.org/wiki/Software_documentation
Consider the Audience: Consider to whom the tool is intended. The answer is to fellow scripters.
With this in mind consider what is written about Software Documentation on wikipedia and analyze what is needed. There is the possibility that not all sections are applicable to this contest.
Remember that even though the audience is scripters, it is a good idea to have a user manual / user documentation.

Tests
Write tests to demonstrate that your tool is working. You should try to convince me that your tool is working correctly.
Do a fitting amount of tests. You will have to evaluate and consider how many and which tests are necessary to show that your tool works.
Remember that tests can only show the presence of bugs, not the absence. Testing properly will however make you discover most mundane errors.
Include the actual tests and what their intent is. What they are supposed to test for. Also include the results of the tests. In the case you find an error in your tool you should naturally try to fix it. If you however discover it so late that you do not have the time, then write it in your submission. Write how you discovered the error, what you suspect the error is. If you have a theory on how to fix the error you should also write down your theory.


How to submit
You must compress your work into either a .zip or .rar file.
Assume only the following programs to be available: Adobe Acrobat Reader, Notepad, RMXP and WinRAR.
All you submit must be checkable with these programs.
In the compressed file there must be:

• A plain-text file containing the script
• A compressed demo file. Preferable .zip or .rar.
• A plain-text file or pdf containing the documentation
• The test cases packaged into one compressed file.

Only what is in the compressed file will be considered when judged.
You must contact me with details on how to acquire the compressed file containing your submission.
You can either send me a pm with the details or email me the file at vobby -at- hotmail -*- com (Basic bot protection -_-)


How the submission will be judged
The reviews will be used as the base for judgment. For this reason will the reviews be created before the actual judgment takes place.
The submissions will be evaluated according to the following criteria:

• Script
  • Completeness - How many of the requirements have been implemented. How complete does the tool feel.
    
  • Correctness - The correctness of the implemented requirements.
    
  • Robustness - Remember that this tool is for scripters. Anticipate that they make errors and try to make the tool stable for typical errors. Good error reporting will be a plus. Robustness is not required, but having a robust tool will give quite an advantage over not having a robust tool.
    
  • Usability - How usable is the tool? How easy is the tool to use? Ease of use is the keyword here.
• Documentation
• Tests

Team submissions
All submissions will be submitted in teams.
This is to encourage scripters to team up on creating their submission for this contest.
The reason for this is founded on my belief that one can make better scripts when working in a team.
There is no limit on team size.
You can enter as a one member team. There is no problem with this. You could potentially also enter a 100 member team. This is also acceptable.
I would suggest 2-3 people per team.
Each team will have exactly ONE team leader.
Team sizes have NO effect on the judging.


How to sign up
You can sign up at any time you want before the 20th December 2007, 23:59 GMT.
When you sign up specify who your team leader is along with all the team members and the total expected number of team members.
You are free to change these specifications at any time before the team registration deadline. The old team leader has to notify me should a team change the team leader. You do not have to notify me when you change team members nor if your number of team members decreases/increases. Here is an example to show you what is expected:

Team leader: Zeriab
Current team members: APerson, AnotherPerson, Zeriab
Expected number of team members: 7

Prizes
All working submission will be reviewed

The first place team will win 3 hours of my time
The second place team will win 2 hours of my time
The third place team will win 1 hours of my time

How my time will be split among each team member is solely at the team leaders’ discretion.
Notes: The time given to the first place team will have priority over the time given to the second and third place teams. Likewise, the time given to the second place team will have priority over the time given to the third place team.
The submission must be in English for your team to be eligible for the prizes.


Timeline
The deadline for team registration is the 20th December 2007, 23:59 GMT.
The hard deadline is on 21th December 2007 at 23:59 GMT.
All submissions will first be reviewed, then judged.
Expect this to take 2-4 weeks depending on the amount of submissions.


Terms and Conditions
All participants must agree to certain conditions when submitting their tool.
A license like the LGPL (Lesser Gnu Public License) would be nice but is not required.
The essence is that the tool can be freely used for non-commercial as well as commercial work. That the tool can be built upon by others enabling them to expand upon it and use it in commercial as well as non-commercial RMXP games. That everyone is permitted to copy and distribute verbatim copies of the tool. The tool is in this context what is submitted for judgment.
Note that you are not required to relinquish your right to demand credits.
It is also fine if you do not allow others to publish their modifications to your tool. They MUST have the ability to change your tool and place it in RMXP games. These games DO NOT have to be encrypted. It is the right to publish the modified tool alone you can choose to prevent.
If you do not agree to these terms DO NOT send in your submission.
This agreement is irreversible if you do not contact me before the judging is published.
This agreement does not hold for future versions of your tool should you make any. (Though I encourage you not to change your terms)


Cross-forum
This is a cross-forum contest meaning that it extends over several forums.
You are free to post this contest at any forum you want. (You are allowed to do a copy-paste of this topic)
The official forums for this contest are:
Chaos Project
Creation Asylum
rmrevolution.com
rmrk.net
hbgames.org

Only at these forums can you expect support and that PMs sent to me will be received.


FAQ
What are views?
A view represents some graphical information to the player.
It could be a Window. It does however not have to be a Window.
The reason why I used views rather than windows is to give you bigger possibilities in how you will create your system.
How you will structure it and what views exactly will be is up to you.
The requirements is that a scripter can use views to provide mouse interactiveness and that the player can see views and interact with the registered views.

What do you mean by 'registering views'?
Each view can be 'registered' to the tool you are creating.
Only registered views are considered when the player clicks.
If there are any views not registered then there will be no mouse interaction.


Thanks
Thanks to Shadow Wolf for support and proof reading.


Final notes
Research what you need to know. Google is your friend. Use it when needed.
Consider me as a client requesting this tool.
People should not have to reverse engineer your tool to use it.

Good luck

 - Zeriab

Alright, this sounds fun. I want to enter. I guess I should find a team, so if anybody wants to work on this with me then post here and we can sign up. I'll join even if I don't find a team in 5 days.

(If only I could get Zeriab to join the team)

Modern, I made a similar post in RMRevolution.  Are you game?  I'm just learning to script so you'd have less of a chance of winning, but you'd have my undying respect and appreciation, and isn't that worth more than 3 hours of Zeriab's time?

Oh - I think Nitt has volunteered to have me, but we need more.  Pop over there and add your name to the list if you want to join us.

Nah, I think that any more then two scripters will kind of get in the way of each other. The process I see is something like this:

The team discusses the design. What they want to include, how they want to do it, etc...
One person writes the script
Second person tests for efficiency and optimizes/revises it
Overview by both scripters: any further revisions they see necessary
Both create stress tests for the optimized version.


I think the designing part of it will get pretty confused if you have more then 2 people at the table. I can't see more then one person working with the script at the same time as working as well as the system I have above, though maybe if the design written is clever enough, you could assign functions of the script to each scripter. In any case, I am sort of thinking that two is the size of team I am looking for. Thanks for the offer though.

that's cool - you won't have to wait long I'm sure.

Modern should get falcon in on this

Good Luck to all participants!
(Wish I can script....)

Working together with more scripters do impose some communication challenges. I believe it is good to learn about them and know how to reduce them. Because then one can better enjoy the benefit of working in a team.

I believe that especially in the design phase is it important to have more team members. In this case there is not really the big difference between 2 and 3 scripters unless you count potential time issues with all 3 scripters being online at the same time.

For the actual scripting it is nice to work two and two on the coding. One write the code and the other watches. Loads of errors are found this way. I find that the efficiency of 2 scripters working like that is more efficient than if they worked separately due to the decrease in errors.

As a your scripting teacher modern, I would recommend you working together with shaz and Nitt. This is due to what I believe you will learn.
Then again. If you could get Falcon to join you I would be delighted


Good luck to all of ya

Zeriab, I have my entry! It's gaurenteed to win! "This isn't serious, but hopefully you'll get a lauch out of it"

Spoiler for Script!:

[runscript=kittenforthewin][Scripterror=failed due to kitten's bad joke]

:3

XD

It did indeed give me a laugh <3

Updated with a FAQ

Bumping the topic to let you all know the deadline for submissions are approaching ^^

This contest was a complete and utter failure considering no submissions were handed in.
I am interested in learning why it was a failure. Did I give too much time, too little time?
Was the work required too big? Was the assignment too boring? Was the topic too big? Was I just unlucky?
If I ever am to do a contest again; What can I do better?
Please do help me and tell me what I did wrong and what I can do better.
I would greatly appreciate it

*hugs*
- Zeriab