"שיבת ציון" - תיעוד למתכנתים

מאת: אראל

אל:

א. עמודים ותנועה

המשחק "שיבת ציון" מתנהל על-פני שטחים גדולים בארץ יהודה. כדי לממש משחק זה, אי אפשר להסתפק בעמוד אחד, ולכן המשחק כולל עמודים רבים - 23 עמודים (המקסימום הוא 25). לכל עמוד יש שם מהצורה "x y" (מילה עם רווח באמצע), כאשר x ו-y הם שני מספרים - מספר העמודה ומספר השורה של העמוד במפת המשחק.

המפה מבוססת, באופן סכימטי ביותר , על מפת ארץ ישראל בזמן שיבת ציון (ע"פ פירוש "דעת מקרא" לספר עזרא). מפת המשחק היא בגודל 5X5. כל משבצת בטבלה למטה מייצגת עמוד (page):   

כפי שניתן לראות בטבלה, רוב העמודים הם מסוג "ש" כלומר "שביל". בעמודים אלה מצויירים שבילים שמובילים מעיר לעיר. חלק מהעמודים מייצגים ערים או איזורים גיאוגרפיים, וגם בהן יש אנשים שאפשר לדבר איתם. למשל, העמוד ששמו "7 9" מתאים למשבצת בטור 7 ובעמודה 9 במפה, שמייצג את העיר "רמה" (בעמוד זה יש ציור של עיר).

המשבצות הריקות מייצגות עמודים שאינם קיימים (למשל, אין עמוד שנקרא "8 6"). במשחק, הן מייצגות הרים בלתי-עבירים, שהמשתמש אינו יכול להגיע אליהם. 

הקואורדינטות של העמוד הנוכחי, שבו נמצא השחקן, נשמרות במשתנים גלובליים - current_pagex , current_pagey .

בכל עמוד יש שתי תיבות-טקסט נסתרות שנקראות onenter ו- onexit . בתיבות אלה יכול המתכנת להכניס פקודות, שיתבצעו באופן אוטומטי בכל פעם שהשחקן ייכנס לעמוד (onenter) או ייצא ממנו (onexit). חלק מהתיבות ריקות - אך הן נמצאות בכל עמוד, כך שיהיה אפשר לשנות את המשחק בקלות בעתיד. דוגמה לשימוש בתיבות אלה: בעמוד שנמצא בטור 6, שורה 5, יש ציפור. בתיבה onenter בעמוד זה כתוב "bird, clickon" ובתיבה onexit כתוב "bird, clickoff". לכן, בכל פעם שנכנסים לעמוד זה, הציפור מתחילה לצייץ, ובכל פעם שיוצאים - הציוצים מפסיקים.

בנוסף לכך, בכל עמוד יש תיבת טקסט הנקראת voice . תיבה זו משמשת להצגת המילים של האנשים שמדברים במהלך המשחק; בכל פעם שדמות כלשהי אומרת משפט כלשהו - המשפט נכתב בתיבת-הטקסט voice, והתיבה זזה ומופיעה מעל ראשה של הדמות שאמרה את המשפט (זה מתבצע ע"י ההליך say - ע' תיעוד בהמשך).

בכל עמוד במפה יש צב שנקרא player , המייצג את השחקן; כאשר השחקן נכנס לעמוד חדש, מופעל הצב שנקרא "player" בעמוד החדש; עבור השחקן, זה נראה כאילו הוא עצמו עבר מעמוד לעמוד.

בכל עמוד יש ציור אחר - הציורים נועדו ליופי, וגם כדי לרמוז לשחקן לאן כדאי לו ללכת (בדרך-כלל כדאי ללכת על השבילים), אך הם אינם משפיעים על התנהלות המשחק בכל צורה שהיא. כלומר, באופן תיאורטי, השחקן לא חייב ללכת על השבילים - הוא יכול ללכת גם על קירות. אולם, בדרך-כלל, כשיש קיר או הר באחד הקצוות של המסך, הוא מציין שאי-אפשר לעבור את קצה המסך לעמוד אחר, כי אין שום עמוד במפה בכיוון זה. אם השחקן ינסה ללכת לשם, הוא ישמע צליל ויראה הודעה bump, ויחשוב שהוא התנגש בקיר - אך למעשה ההתנגשות לא נבעה מכך שמצוייר שם קיר, אלא בגלל שאין עמוד שאליו הוא יכול להגיע (מסקנה: אם המתכנת טועה ושוכח לצייר קיר במקום שבו צריך להיות קיר - השחקן עדיין לא יוכל לעבור לעמוד הסמוך; ואם המתכנת טועה ומצייג קיר במקום שבו לא צריך להיות קיר - השחקן עדיין יוכל לעבור לעמוד הסמוך דרך הקיר).

 

עץ-הקריאות של ההליכים הקשורים לתנועה:

move_by_key - קורא מקש מהמשתמש ומזיז את הצב בהתאם, בעזרת ההליכים הבאים:

• move_north :sign - השחקן זז צפונה (אם sign=1) או דרומה (אם sign=-1) על העמוד. גודל התנועה שווה לקבוע גודל הצעד (STEP). אם התנועה גורמת לכך שמיקומו של השחקן חורג מגבולות העמוד (שנקבעים ע"י הקבוע PAGENORth) - ייקרא ההליך:
  • move_page_north :sign -עובר לעמוד שנמצא מצפון (עבור sign=1) או מדרום (עבור sign=-1) לעמוד הנוכחי. משתמש ב:
    •   enter_page :pagex :pagey :pos  - השחקן מנסה להיכנס לעמוד שנמצא בטור pagex ובשורה pagey על המפה (העמוד שנקרא "x y"), למקום pos בתוך העמוד (pos הוא מהצורה [xcor ycor]). אם אין עמוד כזה בפרוייקט, אז השחקן יישאר באותו עמוד ובאותו מקום, וייקרא ההליך bump. אם יש עמוד כזה, אז קודם-כל יתבצעו הפקודות שנמצאות בתיבת-הטקסט onexit בעמוד הנוכחי, אחר-כך העמוד החדש יהפוך להיות העמוד הפעיל, ואז יתבצעו הפקודות שנמצאות בתיבה onenter בעמוד החדש. 
      • bump - "התנגשות", הליך שנקרא כאשר השחקן מנסה להיכנס לעמוד שאינו קיים; נשמע צליל, והשחקן רואה מעל ראשו הודעה "BUMP". (כאמור למעלה, התנגשות אינה נובעת מהציורים שעל המסך, אלא רק מכך שלא קיים עמוד שאליו אפשר להגיע).
        • ignore_keys - הליך-עזר שמטרתו למחוק מזכרון המחשב את ההקשות שהשחקן הקיש ועדיין לא טופלו. מטרתו של הליך זה היא למנוע מצב שבו השחקן נכנס שוב ושוב ל"התנגשות".
        • ignore - הליך-עזר שמקבל פרמטר-קלט אחד ומתעלם ממנו. משמש כשרוצים לחכות שהמשתמש ילחץ על מקש כלשהו, אך לא מתעניינים במקש שעליו הוא לחץ, ואז כותבים  - ignore readchar.
      • runaway - הליך שגורם לשחקן לברוח מייד מהעמוד שנכנס אליו, אל העמוד הקרוב ביותר. נקרא מתוך תיבות onenter, onexit בעמודים מיוחדים (העמודים שמסביב לירושלים - 7,8 8,7 7,6 6,7)
• move_east :sign - השחקן זז מזרחה (אם sign=1) או מערבה (אם sign=-1) על העמוד. אם התנועה גורמת לכך שמיקומו של השחקן חורג מגבולות העמוד (שנקבעים ע"י הקבוע PAGENORth) - ייקרא ההליך:
  • move_page_east :sign - עובר לעמוד שנמצא ממזרח או ממערב לעמוד הנוכחי.
    • enter_page, bump, runaway - כמו למעלה.

 

 

ב. צבים

השחקן, הדמויות שהוא פוגש, והחפצים שהוא נתקל בהם, מיוצגים ע"י צבים:

• השחקן מיוצג ע"י צב שנקרא player . בכל עמוד במפה יש צב כזה; כאשר השחקן נכנס לעמוד חדש, מופעל הצב שנקרא "player" בעמוד החדש; עבור השחקן, זה נראה כאילו הוא עצמו עבר מעמוד לעמוד.
• לכל צב שמייצג חפץ, יש הוראת-עכבר שכוללת קריאה להליך take - הליך שמקבל כפרמטר מחרוזת, ומוסיף מחרוזת זו לרשימת החפצים שברשות המשתמש (המשתנה הגלובאלי :inventory). ההליך take זה אחראי גם להסתיר את החפץ, כך שלא יוכלו לקחת חפץ אחד פעמיים. למשל, לחפץ שמייצג מטבע של שקל, יש הוראת-עכבר: take "shekel.
• לכל צב שמייצג דמות "פשוטה" (דמות שאי-אפשר לנהל איתה שיחה, כמו חיה או אדם שאינו חלק מהעלילה) - יש הוראת-עכבר שכוללת קריאה להליך greet - הליך שמזיז את הצב ומציג מעל ראשו הודעה קצרה. למשל, לצב שמייצג חתול יש הוראת-עכבר: greet "Mew.
• לכל צב שמייצג דמות שהיא חלק מהעלילה, יש הוראת-עכבר שכוללת קריאה להליך converse - הליך שמנהל שיחה בין הדמות לבין השחקן. כך, כשהשחקן מקליק על הדמות, נפתחת שיחה ביניהם. הקלט להליך זה הוא רשימה של רשימות (ע' למטה בסעיף "ג. שיחות"); לשם נוחות, משתמשים בדרך-כלל בתיבת טקסט שעוברת parse, למשל - בעמוד שמייצג את העיר בית-לחם, יש תיבת-טקסט שנקראת child_text, ולכל אחד מהצבים שמייצגים את הילדים יש הוראת-עכבר מהצורה "converse parse child_text", וכך, כשהשחקן מקליק על אחד הילדים, נפתחת שיחה שנקבעת ע"י טקסט-השיחה שנמצא בתיבת-הטקסט המתאימה. גישה זו מאפשרת לערוך בקלות את טקסט השיחה של הדמויות - אין צורך לשנות את הקוד אלא רק את תיבות הטקסט (כך למשל, אם רוצים לתרגם את המשחק לשפה אחרת, רוב התרגום יתבצע בתיבות הטקסט).

 

הליכים הקשורים לזיהוי סוג הצב:

• object? - מחזיר "אמת" אם הצב הנוכחי הוא חפץ שאפשר לקחת, כלומר - שהוראת-העכבר שלו מתחילה ב"take".

• olive? - מחזיר "אמת" אם הצב הנוכחי הוא זית, כלומר - שהוראת-העכבר שלו היא "take "olive".

• NPC? - מחזיר "אמת" אם הצב הנוכחי הוא דמות שאפשר לדבר איתה, כלומר - שהוראת-העכבר שלה מתחילה ב"converse" או "greet" או "say".

• deaf? - מחזיר "אמת" אם הצב הנוכחי הוא דמות חרשת, כלומר - שהוראת-העכבר שלה כוללת deaf_text.

 

בנוסף לכך, לכל צב יש משתנה-מצב (שנוצר ע"י turtlseown) בשם changed? . משתנה זה מאותחל בתחילת המשחק ל-false, והוא משתנה ל-true אם יש שינוי כלשהו שקשור לצב זה. דמויות אנושיות יכולות להשתנות, במקרים מסויימים, בעקבות שיחה עם השחקן - אם השחקן עזר להם לפתור בעיה כלשהי, אז ערך changed? שלהם ישתנה ל-true (בעזרת הפקודה setchanged? "true), וכך הם "יזכרו" שהם צריכים להתייחס אל השחקן יפה יותר בפעם הבאה שידברו איתו. גם חפצים יכולים להשתנות - למשל, במקרים מסויימים, הם יכולים להישבר, ואז הם מפסיקים לתפקד.

 

ג. דמויות ושיחות

מבנה השיחות מוסבר כאן .

עץ-הקריאות של ההליכים הקשורים לשיחה:

converse :conversation :first_sentence_prefix - נהל שיחה בין הדמות הנוכחית לבין השחקן. לפני תחילת השיחה, ההליך בודק האם המרחק בין השחקן לבין הדמות הוא מספיק קטן כך שהדמות תשמע את השחקן (מרחק זה נמצא בקבוע הגלובלי :CONVERSATION_DISTANCE). אם המרחק גדול מדי - תוצג הודעה האומרת שהדמות לא יכולה לשמוע את השחקן - "too far to hear". אם המרחק מספיק קטן, השיחה מתנהלת בהתאם למבנה-השיחה המועבר בפרמטר :conversation. השיחה מתחילה בתת-השיחה, שהמשפט הראשון שלה מתחיל במחרוזת המועברת בפרמטר :first_sentence_prefix. אם אין תת-שיחה מתאימה - ההליך רק יציג את המחרוזת first_sentence_prefix ויסתיים.

• prefix? :small_string :big_string  - הליך שבודק האם המחרוזת/הרשימה הקטנה (small_string) מופיעה בתחילתה של המחרוזת/הרשימה הגדולה (big_string).
•   talk :conversation :conversation _fragment :prompt - נהל תת-שיחה. מבנה-השיחה כולו מועבר בפרמטר :conversation, ותת-השיחה מועברת בפרמטר :covnersation_fragment. הפרמטר השלישי - prompt - כולל טקסט נוסף שהדמות אומרת לפני שהיא אומרת את המשפט הראשון בתת-השיחה. לאחר מכן, הדמות אומרת את המשפט שנמצא באיבר הראשון של תת-השיחה, ואז מוצגת תיבת-שאלה (question). ההליך משווה את תגובת המשתמש (answer) לאיבר הראשון בכל אחד מהזוגות שבהמשך תת-השיחה; אם יש התאמה, ההליך קורא ל-converse, ומעביר את האיבר האחרון בזוג זה כפרמטר השני ל-converse. כך השיחה תעבור לתת-שיחה אחרת, באופן רקורסיבי. 
  • say :text :color - הליך שנקרא כאשר רוצים שהדמות הנוכחית תגיד משפט כלשהו. המשפט (text) נכתב בתיבת-הטקסט שנקראת "voice", בצבע color; והתיבה זזה מעל לראשה של הדמות הנוכחית.  

    • textheight :text - הליך שמחשב את גובה הטקסט :text. משמש לחישוב המיקום שבו יש לשים את התיבה voice כך שהטקסט ייראה בדיוק מעל ראשה של הדמות המדברת.

  • show_talk_help - הליך שנקרא כאשר השחקן כותב, כתגובה לדמות, את האות "h" (קיצור של help). ההליך מציג עזרה שקשורה לשיחה - איזה מילים כדאי לנסות להגיד לדמות (העזרה מועתקת מתיבת-הטקסט שנקראת talk_help, שנמצאת בעמוד ההתחלתי - "5 5").

greet :text - הדמות הנוכחית אומרת משפט אחד קצר, וגם זזה במקום. הליך זה משמש כהוראת-עכבר עבור דמויות שאין להן תפקיד משמעותי בעלילה, ואין להן טקסט-שיחה מלא (לדוגמה: ראשי הערים, החיות).

• say - ע' למעלה.

think - הליך שמשמש להצגת הודעות. ההודעות מוצגות בצבע קבוע (MESSAGE_color) מעל לראשו של השחקן. הליך זה נקרא במקומות רבים, למשל - כשהשחקן מבקש לראות את רשימת החפצים שלו (inventory), לאחר שהשחקן לוקח חפץ (takeMany), כאשר השחקן לא יכול לקנות חפץ כי אין לו מספיק כסף (buy), או כאשר המשתמש מנסה לעבור לעמוד שאינו קיים (bump). משתמש בהליך:

• say - ע' למעלה.

 

 

ד. חפצים ומסחר

רשימת החפצים שנמצאים ברשותו של השחקן נשמרת במשתנה הגלובלי inventory. בתחילת המשחק הוא מאותחל לרשימה ריקה; במהלך המשחק הוא יכול להשתנות בכמה דרכים:

א. take :item - הליך שנקרא כאשר השחקן מקליק על חפצים מסויימים. ההליך בודק האם המרחק בין השחקן לבין החפץ הוא מספיק קטן (נקבע ע"י הקבוע הגלובלי TAKE_DISTANCE); אם המרחק גדול מדי, תודפס הודעה מתאימה מעל לראשו של השחקן ( too far to take); אם המרחק מספיק קטן, אז החפץ הנוכחי ייעלם מהמסך (ht) כך שהשחקן לא יוכל לקחת אותו שוב, והמחרוזת המועברת כפרמטר תתווסף פעם אחת למשתנה inventory, בעזרת ההליך -

* takeMany :item :count - הליך שמוסיף את המחרוזת :item לרשימת החפצים :inventory, מספר פעמים השווה לפרמטר :count. למשל: takeMany "shekel 5 מוסיף לרשימה inventory 5 איברים: shekel shekel shekel shekel shekel.

ב. drop :item :count - הליך שנקרא כאשר השחקן זורק או נותן חפץ מסויים (בדרך-כלל משתמשים בו בתוך שיחות, כאשר השחקן מסכים לתת חפץ מסויים לדמות מסויימת). ההליך מוריד את המחרוזת :item מרשימת החפצים :inventory, מספר פעמים השווה לפרמטר :count, ומחזיר ערך בוליאני true כדי לציין שהפעולה הצליחה. אם החפץ אינו נמצא ברשימת-החפצים מספיק פעמים - הרשימה לא תשתנה כלל, ההליך יציג הודעה מתאימה מעל ראשו של השחקן ("I dont have enough..."), ויחזיר ערך false. הליך זה משתמש בשני הליכי-עזר כלליים לטיפול ברשימות:

* itemCount :x :list - מחזיר את מספר הפעמים שהאיבר :x מופיע ברשימה :list

* itemRemove :x :count :list - מוציא עד :count מופעים של האיבר :x מהרשימה :list.

ג. buy :item :price - הליך שנקרא כאשר השחקן קונה חפץ מסויים (בדרך-כלל משתמשים בו בתוך שיחות עם סוחרים). ההליך קורא להליך drop (שהוסבר למעלה) כדי להוריד מרשימת החפצים של השחקן את הסכום המתאים - :price מופעים של המטבע הרשמי "shekel". אם הפעולה מצליחה (drop מחזירה true), אז ההליך מוסיף את העצם :item לרשימת החפצים של השחקן, בעזרת ההליך takeMany שנזכר למעלה.

ד.  sell :item :price - הליך שנקרא כאשר השחקן מוכר חפץ מסויים (בדרך-כלל משתמשים בו בתוך שיחות עם סוחרים). אופן הפעולה דומה ל-buy.

ה. makeOil :olivecount :price :oilcount - הליך מיוחד, נקרא רק בשיחה עם בעל בית-הבד בעיר ענתות, שמייצר שמן מזיתים. הסיבה שצריך הליך מיוחד היא, שכדי ליצור שמן צריך שני דברים - גם חומר-גלם (olivecount זיתים), וגם כסף כדי לשלם לבעל בית-הבד (price שקלים); לכן, לפני תחילת הפעולה, ההליך בודק אם יש לשחקן מספיק זיתים וגם מספיק כסף, ורק אם אכן יש לו מספיק - ההליך ממשיך ומוסיף לרשימת החפצים שלו בקבוק אחד של שמן (oil).  

 

 

ה. התחלת המשחק - עץ קריאות

start - התחלת המשחק (הליך זה נקרא כאשר השחקן לוחץ על כפתור "start").

• start_constants - אתחול קבועים של המשחק, למשל צבעי הפונטים שמשמשים לכתיבת הודעות, או גודל הצעד שהשחקן מתקדם עם כל לחיצה על מקש חץ.
• start_game_flags - אתחול משתנים של המשחק, למשל רשימת החפצים שבידי השחקן (inventory) - מאותחלת לרשימה ריקה; וגם משתני מצב, למשל המשתנה player_saw_a_horn "זוכר" האם השחקן כבר ראה את אחת מארבע הקרנות (כאשר השחקן רואה קרן - המשתנה הופך מ-false ל-true, וזה משפיע על חלקים מסויימים במשחק).
• start_pages - אתחול כל העמודים של המשחק.
• move_by_key - הליך התנועה העיקרי - קורא מקש מהמשתמש ומזיז את הצב (ע' תיעוד ועץ-קריאות מפורט בסעיף "א. עמודים ותנועה" למעלה).

  • show_move_help - הליך שנקרא כאשר השחקן לוחץ על "h" (קיצור של help). ההליך מציג עזרה שקשורה לתנועה - על איזה מקשים אפשר ללחוץ (העזרה מועתקת מתיבת-הטקסט שנקראת move_help, שנמצאת בעמוד ההתחלתי - "5 5").

  • inventory - הליך שנקרא כאשר השחקן לוחץ על "i"; מציג את רשימת החפצים שברשותו של השחקן (ע' בסעיף "ד. חפצים ומסחר" למעלה). הרשימה מוצגת ע"י ההליך -

 

ו. הוספת עמודים חדשים

ניתן להרחיב את המשחק ע"י הוספת עמודים חדשים. ראשית יש להחליט, איפה רוצים שהעמוד יהיה במפת המשחק. למשל, נניח שרוצים להוסיף עמוד שמייצג את העיר בית-שמש, 3 משבצות ממערב לירושלים. המקום המתאים במפה הוא טור 4, שורה 7. כדי ליצור עמוד זה, יש להריץ את הפעולה create_page 4 7. העמוד החדש יופיע, ובתוכו מלבן המייצג את הגודל הפעיל של המסך (האיזור שבו השחקן יכול להסתובב). לאחר מכן אפשר:

• לצייר על המסך ציורים מתאימים (למשל, לצייר חומה של עיר, אדמה, צמחים וכו').
• לערוך את תיבות-הטקסט onenter, onexit ולכתוב בהן הוראות לוגו שיתבצעו כאשר השחקן ייכנס לעמוד או ייצא ממנו בהתאמה.
• להוסיף צבים המייצגים חפצים - ולשנות את ההוראה שלהם ל[take "X] כאשר X הוא סוג החפץ.
• להוסיף צבים המייצגים אנשים, להוסיף תיבות-טקסט עם מבני-שיחה מתאימים, לשנות את שם האדם ולשנות את ההוראה שלו ל [converse parse X "],  כאשר X הוא שם תיבת הטקסט (הפרמטר השני ל-converse הוא מרכאות ריקות - כדי שהשיחה תתחיל בשורה הראשונה).

 

 

עץ הקריאות:

create_page :pagex :pagey - יצירת עמוד חדש. אם העמוד כבר קיים, תוצג הודעת שגיאה מתאימה, והעמוד הקיים יוצג על המסך.

• init_page :pagename - אתחול עמוד חדש או עמוד קיים, ע"י ציור מלבן מתאים באמצע העמוד, הוספת תיבות הטקסט onenter, onexit, voice (אם הן לא קיימות), והוספת הצב שנקרא player (אם הוא לא קיים). 
  • rectangle :left :bottom :width :height - צייר מלבן במיקום הנתון על העמוד ובגודל הנתון.   

 

 

קוד

כדי לקרוא את הקוד של המשחק, יש ללחוץ בעזרת הכפתור הימני על הקישור הזה ולבחור "Save Target As", ואז לפתוח את הקובץ בסביבת "microworlds".