NOTICE: Google Maps Platform gaming services is deprecated as of October 18, 2021. Current users will have continued access until December 31, 2022. During this time, we will continue to provide support and fixes to major bugs and outages. See the Gaming Services Transition Guide for resources to help you plan the next steps for your projects.

SDK של מפות Google לקונספטים מרכזיים של Unity

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

הקטעים הבאים מכילים תיאורים של המושגים החשובים ביותר להבנה ולשימוש ב-Maps SDK ל-Unity.

המחלקה והרכיב של MapsService

הכיתה MapsService משמשת כנקודת כניסה לאינטראקציה עם ה-SDK של מפות Google ל-Unity. הוא כולל את ApiKey והוא חושף את הפונקציה GameObjectManager ואת הפונקציה LoadMaps, וגם את אירועים מצינור עיבוד הנתונים GameObject Create.

כדי להשתמש ב-Maps SDK ל-Unity בפרויקט Unity, צריך להוסיף את הסקריפט Service Maps לרכיב ריק ל-GameObject בסצנה. שירות המפה מוסיף באופן אוטומטי את תכונת המפה שנוצרה מ-GameObjects כצאצאים של ה-GameObject של העוגן הזה. שירות השירות (Script) מצורף לאובייקט GamesObject הבסיסי שלכם, ואפשר לגשת למאפיינים הציבוריים שלו ב-Unity Controller – כפי שמוצג כאן.

השירות של מפות Google (סקריפט)

תכונות גיאוגרפיות כ-Unity GameObjects

ה-SDK של מפות ל-Unity מעבד תכונות גיאוגרפיות (כגון מבנה, כבישים ומים) במסד הנתונים של מפות Google, בתור Unity GameObjects במשחקים. בזמן הריצה, הקבצים נוצרים כצאצאים של ה-GameObject שאליו משויך הרכיב MapsService, והם כוללים את השמות בפורמט {MapsFeatureType}({PlaceID}).

אובייקטים של משחק SDK

יצירת אובייקט משחק

במהלך המשחק, ה-SDK שולף נתונים גיאוגרפיים ממסד הנתונים של מפות Google — בתור משבצות וקטוריות סמנטיות (דרך ממשק ה-API של Semanticמשבצות). מתבצע פענוח של הנתונים בזמן אמת, והמערכת הופכת אותם ל-Unity GameObjects. כך תוכלו לגשת לנתוני התכונות במפה (המטא-נתונים והנתונים הגאומטריים) בהקדם האפשרי, כדי שתוכלו להתאים אישית את ה-GameObjects לפני שהם יגיעו לסוף הצינור.

הדבר הראשון ש-Maps SDK for Unity מקבל כשהוא מקבל נתוני וקטור, הוא ליצור MapFeature אובייקט ממנו.

בשלב הביניים בצינור עיבוד הנתונים, MapFeature האובייקטים מתמחים. כלומר, הם הופכים לסוגים ספציפיים (לדוגמה, Google.Maps.Feature.ModeledStructure). האובייקטים הייחודיים של MapFeature מכילים את הפרטים הגיאומטריים (ModeledVolume במקרה של ModeledStructure). הפרטים האלה כוללים גם נתונים ספציפיים ל-FeatureFeature (כמו קודקודים ומשולשים) וגם ממשקים משותפים לגישה לשדות משותפים (כמו תיבות ומשולשים).

נתונים גיאומטריים מומרים ל-Unity Mesh ומתווספים ל-GameObject דרך ה-MeshFilter, ואז מוצגים עם MeshRenderer.

גישה לצינור עיבוד הנתונים

MapFeature נחשפים אליכם דרך אירועים שמופעלים בשלבים שונים של צינור עיבוד הנתונים. דוגמאות לאירועים כאלה: WillCreate אירועים שמופעלים ממש לפני יצירת GameObject, מאפשרים לציין את אפשרויות העיצוב או אפילו לבטל את היצירה, ו-DidCreate אירועים מופעלים מיד לאחר יצירת ה-GameObject, כדי להוסיף או לשנות את הרשת האחרונה.

לדוגמה, אפשר לבדוק ExtrudedStructures אחרי שהמערכת מסיימת WillCreateExtrudedStructureEvent שריפות ולהסתיר את כל המבנים בגובה של פחות מ-20 מטרים (או לדלג על כל המבנים במרחק קצר מ-20 מטרים).

סוגי אירועים

מרחב השמות Google.Maps.Event מכיל סיווג אירועים לכל סוג של תכונות גיאוגרפיות.

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

dynamicMapsService.MapsService.Events.ExtrudedStructureEvents.DidCreate.AddListener(args => {

    // Apply nine-sliced walls and roof materials to this building.
    buildingTexturer.AssignNineSlicedMaterials(args.GameObject);

    // Add a border around the building base using the Building Border Builder class,
    // coloring it using the given border Material.
    Extruder.AddBuildingBorder(args.GameObject, args.MapFeature.Shape, BuildingAndRoadBorder);
});

WillCreate אירועים

אירועי WillCreate מופעלים מיד לאחר יצירת MapFeature, אבל לפני שה-GameObject נוצר ממנו. אירועי WillCreate מאפשרים לך להסתיר או להתאים אישית את ה-GameObjects שנוצרו מתוך MapFeature. ב-WillCreate ארגומנטים מסוג אירוע יש את הטופס הבא:

using System.ComponentModel;
using Google.Maps.Decoded;
using UnityEngine;

namespace Google.Maps {
  public class WillCreateGameObjectEventArgs<T, U>
      : CancelEventArgs where T : IMapObject, U : IGameObjectStyle {

    public readonly T MapObject;
    public U Style;
    public GameObject Prefab;

    Public WillCreateGameObjectEventArgs(T mapObject, U defaultStyle, GameObject prefab) {
      MapObject = mapObject;
      Style = defaultStyle;
      Prefab = prefab;
    }
  }
}
  • הגדרת Cancel (עוברת בירושה מ-CancelEventArgs) ל-true מבטלת את היצירה של ה-GameObject.
  • MapObject הוא לקריאה בלבד.
  • ההגדרה Style מאפשרת להתאים אישית את המראה של ה-GameObject שנוצר.
  • ההגדרה Prefab מחליפה את ה-GameObject שהיה נוצר, עם האישור המקדים.

DidCreate אירועים

אירועי DidCreate מופעלים אחרי יצירת GameObject, אחרי שהוא נוסף לסצנה. הוא מיידע אתכם כשיצירת ה-GameObject הושלמה בהצלחה, וכך תוכלו לבצע עיבוד נוסף. הארגומנטים של DidCreate אירועים מכילים את הטופס הבא:

using System.ComponentModel;
using Google.Maps.Decoded;
using UnityEngine;

namespace Google.Maps {
  public class DidCreateGameObjectEventArgs<T, U>
      : EventArgs where T : IMapObject, U : IGameObjectStyle {

    public readonly T MapObject;
    public GameObject CreatedObject;

    Public DidCreateGameObjectEventArgs(T mapObject, GameObject createdObject) {
      MapObject = mapObject;
      CreatedObject = createdObject;
    }
  }
}
  • MapObject הוא לקריאה בלבד – כך ששינויו לא יגרום לשינוי בסצנה.
  • שינוי CreatedObject ישנה את ה-GameObject שנוסף לסצנה.

מבנים

יש שני סוגים של מבנים: מבנים משוכללים ומבנים מעוצבים.

מבנים מובלטים

מבנים מובלטים נוצרים מהמתאר (כלומר, טביעת רגל דו-ממדית) וגובה. ה-SDK מייצג את רוב המבנים באופן הזה, ויוצר אותו בשלוש דרכים:

  • שימוש בנתוני גובה מהעולם האמיתי (המידע הזה זמין). זוהי התנהגות ברירת המחדל.

  • על ידי ציון גובה קבוע לכל המבנים, תוך התעלמות מהגובה שלהם בעולם האמיתי.

  • על ידי ציון גובה גיבוי לכל המבנים שאינם בגובה אמיתי (ברירת המחדל, הערך הזה מוגדר ל-10 מטרים).

השילוב של שלוש השיטות האלה מאפשר ל-SDK של מפות Google ל-Unity ליצור נוף עירוני עם שונות מציאותית שמשקפת את העולם האמיתי, או עם גובה מבנה קבוע, או שילוב של שתיהן.

מבנים לדוגמה

מבנים לדוגמה נוצרים באמצעות הגישה הרגילה לבניית מודלים בתלת-ממד של משולשים משותפים. הגישה הזו משמשת בדרך כלל למבנים מפורסמים, כמו פסל החירות.

פסל החירות לפי מודל

החלת חומרים

ב-Unity, תהליך הרינדור משתמש ב-shaders, בחומרים ובמרקמים, כדי להוסיף מציאותיות ל-GameObjects. בשיטה 'אזורים כהים', המערכת מוסיפה איך מרקמים, צבעים ותאורה מיושמים בגיאומטריה שמוצגת, תוך שימוש במרקמים, בצבעים ובהגדרות אחרות ששומרים כחומרים. אתם משתמשים בחומרים כדי להגדיר את אופן הרינדור של משטח מסוים - כולל הפניות למרקמים שהוא משתמש בהם, הצגת מידע על אריחים וצביעה.

תריסים הם סקריפטים קטנים שמכילים את הלוגיקה לחישוב הצבע של כל פיקסל - על סמך הקלט של התאורה ועל תצורת החומר. ל-Maps SDK for Unity יש כלי הצללה סטנדרטי למבנים לפי מודל, ועוד אחד לפיצ'רים של מפה בסיסית, אבל יש בו גם תמיכה בחומר מתקדם. הקואורדינטות של מיפוי UV מחושבות עבור אובייקטים של משחקי מפה באופן כזה שאפשר ליישם תוכן בסיסי, והוא נראה סביר ללא שינויים.

כדי ליהנות מאפקטים מהותיים מתקדמים יותר, ה-SDK של מפות Google ל-Unity מספק נתונים נוספים לכל קידומת, באמצעות ערוצי UV נוספים, וכן מספר פונקציות של מעילי צלליות דרך הספרייה GoogleMapsShaderLib. כך ניתן, למשל, לחתוך מרקם של מבנה עם תשעה צלעות – ולחתוך מרקם על הגג, בקרקע, בפינות קירות וקירות אריחים.

מידע נוסף זמין במדריך יצירת חומרים ושימוש בהם במדריך למשתמש של Unity.

ערוצי UV

ערוצי UV עבור כל סוג MapFeature מכילים נתונים בצורה הבאה:

ExtrudedStructure

Walls

כל קיר ב-ExtrudedStructure בנוי בצורת ריבוע בצורת הטופס הבא:

Walls

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

ערוץ 0: (x, y, רוחב, גובה)
x ו-y הם הקואורדינטות ביחס לפינה השמאלית התחתונה של הריבוע הזה (קטע מרובע) של הקיר, ואילו width ו-height הם הרוחב והגובה של הקיר הזה. פעולה זו חלה על כל רביעייה שמיוצרת על הקיר.
גג

אפשר להגדיר מרקם של גג כך שהוא יהיה מיושר לציר או מכוון לכיוון הExtrudedStructure. מגדירים זאת באמצעות האובייקט ExtrudedStructureStyle.

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

Region

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

Segment

ערוץ 0: (x, y, רוחב, אורך)
x ו-y הם הקואורדינטות של כל קצוות, שמחושבים כאילו הם ישרו לחלוטין – כדי לאפשר מרקם להתכופף לפינות. width ו-length מגדירים את מידות הפלח.

ModeledStructure

ערוץ 0:
כל הקואורדינטה מוגדרת לערך (0, 0, 0, 0) כי לא מתבצעת כרגע הטמעה של קואורדינטות המרקם.

מפות GoogleShaderLib

ערכת ה-SDK של מפות Google ל-Unity כוללת ספריית תוכנות הצללה בשם GoogleMapsShaderLib, כדי לעזור לכם ליצור תוכנות הצללה שעובדות היטב עם FeatureFeature GameObjects. הספרייה מיושמת בקובץ GoogleMapsShaderLib.cginc. כדי להשתמש בספרייה, יש לכלול את ההנחיה הבאה: #include בקטע הסימונים CGPROGRAM, בסקריפט של תוכנת הצללה (shader).

CGPROGRAM
// ...
#include "/Assets/GoogleMaps/Materials/GoogleMapsShaderLib.cginc"
// ...
ENDCG

ספריית ההצללה מקובצת בתוך GoogleMaps.unitypackage. אחרי ייבוא החבילה, הכתובת GoogleMapsShaderLib.cginc מופיעה בתוך תיקיית הפרויקט /Assets/GoogleMaps/Materials/.

חיתוך תשעים

GoogleMapsShaderLib כולל פונקציית נוחות שניתן להשתמש בה במצלחי צלעות כדי לספק nine-slicing מרקמים. חיתוך תשעה הוא טכניקה של כיסוי משטחים עם מרקם, שבו המרקם מחולק לתשעה חלקים באמצעות סדרת גבולות. בתוך הגבולות בין הגבולות, הגבולות בתוך הגבולות נשארים קבועים, כמו שאפשר לראות כאן:

חיתוך תשעים

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

בדרכים (לדוגמה, קטע תלול) מאפשר מדרכה ברוחב קבוע, אך עם מספר משתנה של נתיבים, בהתאם לרוחב הכביש.

ניתן להשתמש בחיתוך בן תשע שורות על ידי הכללת GoogleMapsShaderLib.cginc בתפריט, ואז קריאה לפונקציה nineSlice. תוכנות הצללה וחומרים לדוגמה כלולים ב-GoogleMaps.unitypackage כדי להראות איך אפשר להשתמש בפונקציה nineSlice כדי ליצור גורד שחקים מציאותי בגודל משתנה – בלי למתוח או לדמע

מיקום לדוגמה
/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing
מיקום לדוגמה ב-Sshader
/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing/BuildingWall.shader

ניתן להשתמש ב-9 פרוסות בכל MapFeature, פרט ל-ModeledStructures, שאין להן כרגע קואורדינטות של טקסטורה.

מערכת הקואורדינטות

מערכת ה-SDK של מפות Google ל-Unity משתמשת במקרן האינטרנט מרקטור כדי להמיר בין פלטפורמות WGS 84 של קווי אורך ורוחב של Unity לקרטיזם (Vector3).

ערכי וקטור3 הם יחסיים למקור צף, שלרוב מוגדר כמיקום ההתחלה של המשתמש. כתוצאה מכך, אין לשמור על ערכי Vector3 מחוץ לסשן (כלומר, בשרת שלכם או במכשיר של המשתמש). מומלץ לציין מיקומים פיזיים בעולם באמצעות זוגות קווי אורך ורוחב.

מקור צף משמש למניעת בעיות יציבות של נקודה צפה (floating-point). Unity's בכיתת Vector3 נעשה שימוש במספרים של נקודות צפות בהתאמה מדויקת, והדחיסות של מספרים שניתן לייצג בצורה צפה בירידה פוחתת ככל שההיקף שלהם עולה (כלומר, מספרים גדולים יותר של נקודות צפות הופכים להיות פחות מדויקים). תוכלו לעדכן את המקור הצף בכל פעם שמשתמשים יתרחשו רחוק מהמקור, כדי שתהיה בעיה. אפשר להגדיר אותו לערך קטן יחסית (לדוגמה, 100 או 200 מטרים) או גדול יותר (יותר מקילומטר), בהתאם לתדירות שבה אתם רוצים לעדכן פריטים.

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

ב-Maps SDK for Unity יש פונקציות המרה שאפשר להמיר בין Google.Maps.LatLng ל-Unity Worldspace (Vector3) שמביא בחשבון את המקור הצף ואת קנה המידה.

טעינת השגיאות

שגיאות שמתרחשות בזמן טעינת נתוני המפה מהרשת ניתנות לטיפול באירוע MapLoadErrorEvent. {0}ה-SDK של מפות ל-Unity מטפל במרבית סוגי השגיאות בעצמו אם לא מוסיפים גורם מטפל לאירועים. עם זאת, יש שגיאה שדורשת פעולה כלשהי מהאפליקציה שלכם. הנתון הזה מפורט MapLoadErrorArgs.DetailedErrorCode ומתואר בהמשך.

UnsupportedClientVersion

הופסקה התמיכה בגרסה הזו של SDK SDK ל-Unity, ייתכן בשילוב עם מפתח ה-API הנוכחי. בדרך כלל, האפליקציה צריכה לבקש מהמשתמש לעדכן לגרסה חדשה יותר של האפליקציה.

בדרך כלל, השגיאה הזו מופיעה כי ה-SDK של מפות Google ל-Unity ישן מדי. במקרים נדירים, אנחנו עשויים להשתמש באפשרות הזו אם גילינו בעיה קריטית בגרסה של ה-SDK של מפות Google ל-Unity או עם מפתח API. נעשה כל מאמץ לעדכן על כך ולהבטיח שהבעיה לא תקרה עד שתהיה גרסה פעילה של האפליקציה שאפשר לעדכן.

מומלץ לוודא שהאפליקציה כוללת נתיב שדרוג מתאים במקרה ששגיאה זו מתרחשת. המשתמשים יוכלו לעבור לגרסה חדשה יותר של האפליקציה, עם גרסת SDK נתמכת. מידע נוסף זמין במסמך Client Kill Switch.

בעיות ידועות

תכונות המפה הבסיסית מעובדות הלוך ושוב ללא בדיקת z, כי כל התכונות מהסוג הזה מעובדות באותו מטוס. עליכם להגדיר את ה-z-testing ל-ZTest Always (חומרי בדיקה חלופיים) בכל החומרים החלופיים שאתם מחילים על תכונות הבסיס של המפה, כדי לוודא שהמערכת תעבד אותם כראוי.

ב-GoogleMaps.unitypackage מופיעה בקשה לדוגמה שמטפלת בבעיות האלה ב-Google. הכתובת נקראת "BaseMapTextured.shader, והיא נמצאת בתיקייה /Assets/GoogleMaps/Materials/. כדי להשתמש בו על חומר, בוחרים באפשרות Google > מפות > צלליות > Basemap מרקם מהתפריט הנפתח של הצללית בכלי לבדיקת חומרים.

כשמעצבים אובייקט Feature.Region או אובייקט Feature.AreaWater, אפשר להוסיף מילוי באמצעות חומר, צבע בהתאמה אישית או צבע שנוצר באופן אוטומטי באמצעות האובייקט FillModeType. Auto הצבעים נוצרים על סמך הערך של סוג השימוש באזור.